Help us shape the future of Go! Take the 2026 Go Developer Survey

cache

package module
v0.0.0-...-c788970 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Sep 21, 2026 License: Apache-2.0 Imports: 23 Imported by: 0

Documentation

Index

Constants

View Source 
const (
	DefaultMaxRows        = 5000
	DefaultMaxBytes int64 = 4 << 20
)
View Source 
const (
	BypassTx          = "tx"
	BypassLock        = "lock"
	BypassNoStatement = "no-statement"
	BypassGeneration  = "gen-failure"
	BypassDisabled    = "disabled"
	BypassSkip        = "skip"
	BypassKey         = "key"
)

Variables

This section is empty.

Functions

func Cache 

func Cache(ctx context.Context, options ...QueryOption) context.Context

func NewContext 

func NewContext(ctx context.Context) context.Context

func Skip 

func Skip(ctx context.Context) context.Context

Skip is honored by the driver only when global caching is enabled.

func Tags 

func Tags(tags ...string) tagOption

Tags can annotate a cached query or invalidate entries carrying the same user tags.

func Touches 

func Touches(ctx context.Context, tables ...string) context.Context

Types

type Driver 

type Driver struct {
	dialect.Driver
	// contains filtered or unexported fields
}

As with database/sql, callers must close Rows to release database resources.

func New 

func New(driver dialect.Driver, options ...Option) (*Driver, error)

func (*Driver) BeginTx 

func (d *Driver) BeginTx(ctx context.Context, options *dialect.TxOptions) (dialect.Tx, error)

func (*Driver) DB 

func (d *Driver) DB() *sql.DB

func (*Driver) Exec 

func (d *Driver) Exec(ctx context.Context, query string, arguments []any) (dialect.Result, error)

func (*Driver) Invalidate 

func (d *Driver) Invalidate(ctx context.Context, options ...InvalidateOption) error

func (*Driver) Query 

func (d *Driver) Query(ctx context.Context, query string, arguments []any) (dialect.Rows, error)

func (*Driver) Stats 

func (d *Driver) Stats() *Stats

func (*Driver) Tx 

func (d *Driver) Tx(ctx context.Context) (dialect.Tx, error)

type Entry 

type Entry struct {
	// contains filtered or unexported fields
}

Entry is an immutable SELECT result, shared by cache levels and readers.

func DecodeEntry 

func DecodeEntry(data []byte) (*Entry, error)

DecodeEntry retains encoded cells; replay decodes their values on first use.

func (*Entry) Bytes 

func (e *Entry) Bytes() ([]byte, error)

Bytes memoizes the wire representation. The returned bytes belong to the caller. SEF preserves time instants but normalizes their locations to UTC.

func (*Entry) Columns 

func (e *Entry) Columns() []string

func (*Entry) Len 

func (e *Entry) Len() int

type GenerationStore 

type GenerationStore interface {
	// Now supplies the same microsecond clock used by Load and Bump.
	Now(ctx context.Context) (uint64, error)
	// Load returns one token per tag. Stores that can lose tags must initialize
	// missing tags with the current time to reject entries predating that loss.
	Load(ctx context.Context, tags []string) ([]uint64, error)
	// Bump sets each token to max(previous+1, current time).
	Bump(ctx context.Context, tags []string) error
}

func NewMemoryGenerations 

func NewMemoryGenerations() GenerationStore

type Info 

type Info struct {
	Hit       bool
	Stale     bool
	Level     string
	Tables    []string
	PointRead bool
	Bypass    string
}

Info belongs to one query; callers must not share it between concurrent queries.

func WithInfo 

func WithInfo(ctx context.Context) (context.Context, *Info)

type InvalidateOption 

type InvalidateOption interface {
	// contains filtered or unexported methods
}

func All 

func All() InvalidateOption

func Rows 

func Rows(table string, ids ...any) InvalidateOption

Rows invalidates the named rows and table-wide reads that may include them.

func Tables 

func Tables(tables ...string) InvalidateOption

Tables invalidates both list and point reads of the named tables.

type Invalidator 

type Invalidator struct {
	// contains filtered or unexported fields
}

func NewInvalidator 

func NewInvalidator(generations GenerationStore) *Invalidator

func (*Invalidator) Invalidate 

func (i *Invalidator) Invalidate(ctx context.Context, options ...InvalidateOption) error

type Key 

type Key [16]byte

func (Key) String 

func (k Key) String() string

type Level 

type Level interface {
	// Get returns (nil, nil) on a miss.
	Get(ctx context.Context, key Key) (*Entry, error)
	Set(ctx context.Context, key Key, entry *Entry, ttl time.Duration) error
	Delete(ctx context.Context, keys ...Key) error
}

func ContextLevel 

func ContextLevel() Level

func NewMemory 

func NewMemory(maxEntries int, maxBytes int64) Level

NewMemory bounds entries and estimated bytes independently; zero disables a bound. Negative bounds panic. Nonpositive Set TTLs remove an existing entry.

type Limits 

type Limits struct {
	MaxRows  int
	MaxBytes int64
}

Limits bounds one recorded result. Nonpositive fields select the defaults.

type Option 

type Option func(*Driver) error

func CacheTables 

func CacheTables(tables ...string) Option

func Generations 

func Generations(store GenerationStore) Option

func Global 

func Global(enabled bool) Option

func HotTable 

func HotTable(window time.Duration, bumps int) Option

HotTable demotes list queries to TTL-only invalidation when a table exceeds bumps within window. Either value set to zero disables automatic demotion. The default is 50 bumps within 10 seconds. Point reads are not demoted.

func Levels 

func Levels(levels ...Level) Option

func OnError 

func OnError(handler func(context.Context, error)) Option

func SWR 

func SWR(duration time.Duration) Option

SWR permits serving expired entries while refreshing them in the background. A zero window disables stale-while-revalidate, which is the default.

func Schema 

func Schema(tables ...*schema.Table) Option

Schema isolates entries across changes to the tables' result shapes and unique keys.

func Singleflight 

func Singleflight(enabled bool) Option

func SingleflightWait 

func SingleflightWait(duration time.Duration) Option

SingleflightWait bounds waiting for a leader whose caller may never close rows.

func SkewMargin 

func SkewMargin(margin time.Duration) Option

func SkipTables 

func SkipTables(tables ...string) Option

func TTL 

func TTL(duration time.Duration) Option

func TTLOnlyTables 

func TTLOnlyTables(tables ...string) Option

func TxReads 

func TxReads(policy TxReadPolicy) Option

func Views 

func Views(views map[string][]string) Option

func WithLimits 

func WithLimits(limits Limits) Option

type QueryOption 

type QueryOption interface {
	// contains filtered or unexported methods
}

func DependsOn 

func DependsOn(tables ...string) QueryOption

func NoFill 

func NoFill() QueryOption

func TTLOnly 

func TTLOnly() QueryOption

func WithSWR 

func WithSWR(duration time.Duration) QueryOption

WithSWR overrides the driver's stale window for this query. Nonpositive durations disable stale-while-revalidate.

func WithTTL 

func WithTTL(duration time.Duration) QueryOption

type Stats 

type Stats struct {
	Misses             atomic.Uint64
	Fills              atomic.Uint64
	StaleHits          atomic.Uint64
	Refreshes          atomic.Uint64
	DroppedFills       atomic.Uint64
	SingleflightShared atomic.Uint64
	// contains filtered or unexported fields
}

Stats is safe for concurrent updates. It must not be copied after first use.

func (*Stats) RecordBump 

func (s *Stats) RecordBump(table string)

func (*Stats) RecordBypass 

func (s *Stats) RecordBypass(reason string)

func (*Stats) RecordHit 

func (s *Stats) RecordHit(level string)

func (*Stats) Snapshot 

func (s *Stats) Snapshot() StatsSnapshot

Snapshot reads counters independently and reports current demotion state.

type StatsSnapshot 

type StatsSnapshot struct {
	Hits               map[string]uint64
	Misses             uint64
	Fills              uint64
	StaleHits          uint64
	Refreshes          uint64
	DroppedFills       uint64
	Bypasses           map[string]uint64
	SingleflightShared uint64
	Bumps              map[string]uint64
	// DemotedTables lists automatically demoted tables, excluding manual policies.
	DemotedTables []string
}

type Tx 

type Tx struct {
	// contains filtered or unexported fields
}

func (*Tx) Commit 

func (t *Tx) Commit() error

func (*Tx) Exec 

func (e *Tx) Exec(ctx context.Context, query string, arguments []any) (dialect.Result, error)

func (*Tx) Query 

func (e *Tx) Query(ctx context.Context, query string, arguments []any) (dialect.Rows, error)

func (*Tx) Rollback 

func (t *Tx) Rollback() error

type TxReadPolicy 

type TxReadPolicy uint8
const (
	TxReadsBypass TxReadPolicy = iota
	// TxReadsUntilWrite is only safe at read committed isolation. Stronger
	// isolation may observe cached results newer than the transaction snapshot.
	TxReadsUntilWrite
)

Source Files

View all Source files

Directories

Path Synopsis
internal
testschema
testschema/entity
testschema/enttest
testschema/group
testschema/migrate
testschema/pet
testschema/runtime
testschema/schema
testschema/user
Package redis provides a Redis cache level and server-clock generation store.
 Package redis provides a Redis cache level and server-clock generation store.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.