Documentation
¶
Overview ¶
Package database owns PostgreSQL handles and checked query/transaction mechanics.
Index ¶
- Variables
- func Lookup(err error) (bool, error)
- func Missing(err error) error
- func OpenRaw(url string) (*sql.DB, error)
- func QueryError(err error, q string) error
- func Rebind(query string) string
- func Transact[T any](ctx context.Context, db *DB, fn func(*Tx) (T, error)) (T, error)
- type DB
- func (d *DB) Begin(ctx context.Context) (*Tx, error)
- func (d *DB) Close() error
- func (d *DB) Exec(query string, args ...any) (sql.Result, error)
- func (d *DB) FailNextStatement(fragment string) func()
- func (d *DB) FailStatementAfter(fragment string, skip int) func()
- func (d *DB) FailStatements(fragment string, n int) func()
- func (d *DB) HoldExclusive(ctx context.Context, key int64) (release func(), err error)
- func (d *DB) InTx(ctx context.Context, fn func(*Tx) error) error
- func (d *DB) Ping() error
- func (d *DB) Pool() *sql.DB
- func (d *DB) Query(query string, args ...any) (*Rows, error)
- func (d *DB) QueryRow(query string, args ...any) *Row
- func (d *DB) ReadSnapshot(ctx context.Context) (*Tx, error)
- func (d *DB) SQL() Handle
- type DBTX
- type Handle
- func (d Handle) ExecContext(ctx context.Context, q string, args ...any) (sql.Result, error)
- func (d Handle) QueryContext(ctx context.Context, q string, args ...any) (*sql.Rows, error)
- func (d Handle) QueryRowContext(ctx context.Context, q string, args ...any) *sql.Row
- func (d Handle) WithExecutor(executor DBTX) Handle
- type Queryer
- type Row
- type Rows
- type Tx
Constants ¶
This section is empty.
Variables ¶
var ErrHeldElsewhere = errors.New("held by another session")
ErrHeldElsewhere: another session holds the exclusive lock asked for.
var ErrInjectedFailure = fmt.Errorf("injected statement failure")
Functions ¶
func Lookup ¶
Lookup sorts a single-row read's outcome: found, absent, or failed.
found, err := Lookup(a.DB.QueryRow(q, id).Scan(&x))
func Missing ¶
Missing classifies a single-row read's absence: sql.ErrNoRows becomes a fault.NotFound that still matches sql.ErrNoRows, and any other error or nil passes through. Use it where an owner reads a record by its identity, never after a write: a write that returns no row was not recorded, which is a failure, not an absence.
func QueryError ¶
Types ¶
type DB ¶
type DB struct {
// contains filtered or unexported fields
}
DB owns the PostgreSQL connection pool and rebinds ? placeholders to $n. Concurrency is controlled by transactions, row locks and conditional writes. Close result sets before issuing another query to avoid exhausting the pool. Values are never rewritten: binary content belongs in bytea, not TEXT.
func OpenWith ¶
OpenWith is Open with every connection made by dial (nil is the default dialer). The test database harness gives its own, which closes connections without leaving them waiting in TIME_WAIT.
func (*DB) FailNextStatement ¶
FailNextStatement scopes a one-shot fault to this pool and its transactions. The returned cleanup only clears this installation, never a newer one.
func (*DB) FailStatementAfter ¶
FailStatementAfter lets skip matching statements run, then fails the next one. Use it when an earlier read of the same query is not the one a test is about.
func (*DB) FailStatements ¶
FailStatements fails the next n statements containing fragment: a fault that outlasts a caller's retries.
func (*DB) HoldExclusive ¶
HoldExclusive takes a Postgres session-level advisory lock on this database under key and keeps the one connection that holds it until release is called (or the process ends). It never waits: a lock another session holds is ErrHeldElsewhere at once. The lock belongs to that connection, so a lost connection (a Postgres restart, a network cut) releases it without telling the holder; callers name that as accepted.
func (*DB) Pool ¶
Pool is for infrastructure adapters such as River and schema installation. Domain queries use SQL so they retain the checked query boundary.
func (*DB) ReadSnapshot ¶
ReadSnapshot keeps related read-only facts at one database revision.
type Handle ¶
type Handle struct {
DBTX
// contains filtered or unexported fields
}
func (Handle) ExecContext ¶
func (Handle) QueryContext ¶
func (Handle) QueryRowContext ¶
func (Handle) WithExecutor ¶
WithExecutor decorates statement execution while retaining this handle's fault scope. It is used by query-budget tests and other infrastructure instrumentation.
type Queryer ¶
type Queryer interface{ SQL() Handle }
Generated queries use database/sql directly, on the same pool or transaction as handwritten queries. Keep failure injection on this boundary too, so migrating a write cannot silently bypass the atomicity tests.
type Row ¶
type Row struct {
// contains filtered or unexported fields
}
Row is a single-row result whose errors name their statement.
type Rows ¶
Rows is a result set whose errors name their statement. Close reports an iteration error the caller never asked about, so a loop that ended early is at least loud.
Source Files