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 ¶
Constants ¶
const ( ConstraintUnique = "unique" ConstraintForeignKey = "foreign_key" ConstraintNotNull = "not_null" ConstraintCheck = "check" ConstraintExclusion = "exclusion" )
Constraint kinds a ConstraintError reports.
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 ErrPermissionDenied = errors.New("store: permission denied")
ErrPermissionDenied marks a statement the database refused for the connection's account: a missing privilege, or a write on a read-only server or transaction. Providers wrap driver errors with it.
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 ConstraintError ¶ added in v0.1.11
ConstraintError is a write the database rejected for violating a constraint. Providers classify driver errors into it. Constraint and Columns serve the gateway only: a client sees the kind and the fields it may see, never the constraint name or the database's message.
func (*ConstraintError) Error ¶ added in v0.1.11
func (e *ConstraintError) Error() string
Error implements error without the driver message.
func (*ConstraintError) Unwrap ¶ added in v0.1.11
func (e *ConstraintError) Unwrap() error
Unwrap returns the driver error.
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 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
}
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