Documentation
¶
Overview ¶
Package store defines the database execution abstraction used by core tools.
DB and Tx are minimal interfaces satisfied by *sql.DB / *sql.Tx via thin adapters in x/providers. Core packages depend on these interfaces so they can be tested with hand-written fakes and remain free of any database driver import. Iter turns a Rows stream into a range-friendly iterator for zero-materialization streaming of large result sets.
Index ¶
- Variables
- func Iter(rows Rows) iter.Seq2[Row, error]
- type DB
- type FakeDB
- type FakeRows
- type FakeTx
- func (t *FakeTx) Commit() error
- func (t *FakeTx) ExecContext(_ context.Context, _ string, _ ...any) (Result, error)
- func (t *FakeTx) QueryContext(_ context.Context, _ string, _ ...any) (Rows, error)
- func (t *FakeTx) Rollback() error
- func (t *FakeTx) RollbackTo(_ context.Context, sp Savepoint) error
- func (t *FakeTx) Savepoint(_ context.Context, name string) (Savepoint, error)
- type IsolationLevel
- type LoggedExec
- type LoggedQuery
- type Prepared
- type PreparedDB
- type Preparer
- type Result
- type Row
- type Rows
- type Savepoint
- type Tx
- type TxBeginner
- type TxOptions
Constants ¶
This section is empty.
Variables ¶
var ErrNoBeginFn = errors.New("store: no BeginFn configured")
ErrNoBeginFn is returned when a FakeDB has no BeginFn configured.
var ErrNoExecFn = errors.New("store: no ExecFn configured")
ErrNoExecFn is returned when a FakeDB has no ExecFn configured.
var ErrNoQueryFn = errors.New("store: no QueryFn configured")
ErrNoQueryFn is returned when a FakeDB has no QueryFn configured.
var ErrScanBeforeNext = errors.New("store: Scan called before Next")
ErrScanBeforeNext is returned when Scan is called before Next.
Functions ¶
func Iter ¶
Iter returns a sequence yielding decoded rows and a terminal error. It closes the Rows when iteration ends — whether by exhausting the cursor, an early break, or a terminal error — so callers need not close it themselves. Use it with range over func to stream large result sets without materializing them.
Types ¶
type DB ¶
type DB interface {
QueryContext(ctx context.Context, query string, args ...any) (Rows, error)
ExecContext(ctx context.Context, query string, args ...any) (Result, error)
}
DB is the minimal database interface core tools depend on. *sql.DB satisfies it via a thin adapter in x/providers; tests use hand-written fakes.
type FakeDB ¶
type FakeDB struct {
QueryFn func(ctx context.Context, query string, args ...any) (Rows, error)
ExecFn func(ctx context.Context, query string, args ...any) (Result, error)
BeginFn func(ctx context.Context, opts *TxOptions) (Tx, error)
Queries []LoggedQuery
Execs []LoggedExec
TxBegun int
}
FakeDB is a hand-written DB and TxBeginner for tests. Configure the *Fn fields to control responses; calls are recorded for assertion.
func (*FakeDB) ExecContext ¶
type FakeRows ¶
FakeRows is a hand-written Rows implementation for tests.
func NewFakeRows ¶
NewFakeRows builds a FakeRows with the given columns and rows.
type FakeTx ¶
FakeTx is a hand-written Tx for tests.
func (*FakeTx) ExecContext ¶
func (*FakeTx) QueryContext ¶
QueryContext and ExecContext on FakeTx defer to package-level helpers; tests usually configure a shared FakeDB for tx behavior. For simplicity they return zero values unless overridden via fields.
type IsolationLevel ¶
type IsolationLevel uint8
IsolationLevel names a transaction isolation level.
const ( // LevelReadUncommitted allows dirty reads. LevelReadUncommitted IsolationLevel = iota // LevelReadCommitted is the default for most databases. LevelReadCommitted // LevelRepeatableRead prevents non-repeatable reads. LevelRepeatableRead // LevelSerializable is the strictest isolation. LevelSerializable )
type LoggedExec ¶
LoggedExec records an ExecContext call.
type LoggedQuery ¶
LoggedQuery records a QueryContext call.
type Prepared ¶
type Prepared interface {
QueryContext(ctx context.Context, args ...any) (Rows, error)
ExecContext(ctx context.Context, args ...any) (Result, error)
Close() error
}
Prepared is a reusable statement.
type PreparedDB ¶
type PreparedDB struct {
DB
// contains filtered or unexported fields
}
PreparedDB uses an optional bounded prepared-statement cache while preserving the DB interface. A non-Preparer DB is passed through unchanged.
func WithPreparedCache ¶
func WithPreparedCache(db DB, max int) *PreparedDB
WithPreparedCache wraps db. max <= 0 disables preparing.
func (*PreparedDB) Close ¶
func (d *PreparedDB) Close() error
Close clears all prepared statements. It does not close the wrapped DB.
func (*PreparedDB) ExecContext ¶
ExecContext implements DB.
func (*PreparedDB) QueryContext ¶
QueryContext implements DB.
type Rows ¶
type Rows interface {
Next() bool
Scan(dest ...any) error
Columns() ([]string, error)
Close() error
Err() error
}
Rows is a forward-only cursor over query results. Callers must Close it, typically with defer. It mirrors the subset of *sql.Rows used by core tools.
type Savepoint ¶
type Savepoint struct{ Name string }
Savepoint names a savepoint within a transaction.
type Tx ¶
type Tx interface {
QueryContext(ctx context.Context, query string, args ...any) (Rows, error)
ExecContext(ctx context.Context, query string, args ...any) (Result, error)
Commit() error
Rollback() error
Savepoint(ctx context.Context, name string) (Savepoint, error)
RollbackTo(ctx context.Context, sp Savepoint) error
}
Tx is a transaction boundary. ACID is an inseparable part of the relational model; tools may execute multiple writes within a Tx. Every Tx must end in Commit or Rollback (invariant I10).
type TxBeginner ¶
TxBeginner begins a transaction. *sql.DB satisfies it via an adapter.
type TxOptions ¶
type TxOptions struct {
Isolation IsolationLevel
ReadOnly bool
}
TxOptions configures a transaction.
Source Files