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 ErrConnectionLost = errors.New("store: connection lost during the statement")
ErrConnectionLost marks a statement whose connection broke while it ran: the database may or may not have carried it out. Providers wrap driver errors with it. A broken connection a driver reports before sending the statement (driver.ErrBadConn) is not one.
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.
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 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 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
Directories
¶
| Path | Synopsis |
|---|---|
|
Package storetest holds hand-written fakes of the store interfaces for tests: a DB, a Tx and Rows whose answers the test configures and whose calls it reads back, without a mocking library.
|
Package storetest holds hand-written fakes of the store interfaces for tests: a DB, a Tx and Rows whose answers the test configures and whose calls it reads back, without a mocking library. |