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 ( ErrMissingRelation = errors.New("store: a table the statement names does not exist") ErrMissingColumn = errors.New("store: a column the statement names does not exist") )
ErrMissingRelation and ErrMissingColumn mark a statement naming a table or a column the database does not have (any more): its schema changed under a running configuration. Providers wrap driver errors with them.
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 ErrInterrupted = errors.New("store: statement interrupted")
ErrInterrupted marks a statement the database interrupted as it ran (the KILL QUERY of one past its deadline): a single statement is rolled back, but a procedure's earlier statements may have taken effect, so a write interrupted may or may not have been carried out. Providers wrap driver errors with it.
var ErrInvalidValue = errors.New("store: a value does not fit its column")
ErrInvalidValue marks a statement the database refused for a value the caller gave: one its column's type cannot hold (text that is no number or date, a number out of range, a string too long). It tells nothing of the database's health. Providers wrap driver errors with it.
var ErrNotConnected = errors.New("store: no connection to the database could be made")
ErrNotConnected marks a statement that was never sent: no connection to the database could be made for it (the server refused or did not answer the connection, or is not one the provider serves), so it did not take effect, whatever else the error wraps (a network error, a deadline). Providers wrap driver errors with it.
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 ErrRejected = errors.New("store: the database refused the statement")
ErrRejected marks a statement the database refused as written, for a reason of the statement's own (its syntax, its types, a lock or deadlock it met): not one telling of the database's health (out of connections, memory or disk, shutting down, a broken connection), which providers leave unmarked. Providers wrap driver errors with it.
var ErrStalePlan = errors.New("store: the statement's cached plan no longer matches its table")
ErrStalePlan marks a statement whose prepared plan, cached on its connection, no longer matches its table after a schema change. The database refused it before running it, and dropped the plan: run again, it is planned afresh. Providers wrap driver errors with it.
var ErrStatementTimeout = errors.New("store: statement stopped at its timeout")
ErrStatementTimeout marks a statement the database stopped at its timeout (a server-side statement timeout, or the cancel request of a request whose deadline passed): the database rolled it back, so it did not take effect. 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.
func IterNamed ¶ added in v0.1.15
IterNamed is Iter with the columns named by position: names[i] keys the i-th column whatever the database called it (databases name computed columns differently, and may give two the same name). A nil names keeps the database's names; a count that differs from the columns is an error.
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 ( // LevelDefault is the database's default level: the zero value, so that // options naming no level ask for no particular one. LevelDefault IsolationLevel = iota // LevelReadUncommitted allows dirty reads. LevelReadUncommitted // 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.
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. |