Documentation
¶
Overview ¶
Package database owns PostgreSQL handles and checked query/transaction mechanics.
Index ¶
- Constants
- Variables
- func Lookup(err error) (bool, error)
- func Missing(err error) error
- func OpenRaw(url string) (*sql.DB, error)
- func OwnServerSupported(versionNum int) error
- func QueryError(err error, q string) error
- 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) 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) OwnServer(ctx context.Context) (int, error)
- func (d *DB) Ping() error
- func (d *DB) Pool() *sql.DB
- 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 Tx
Constants ¶
const ( OwnPostgresMin = 16 OwnPostgresMax = 16 )
The PostgreSQL major versions AppTown runs its own database on, built-in or -db-url. A release supports one range: its backups dump with the newest major's pg_dump, which dumps any older server in the range, and the built-in database a restore loads into is made at the newest, so a dump from anywhere in the range restores. Raising OwnPostgresMax is a release of its own: the pinned client image and the built-in database's image move with it. App databases are not bound by this.
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 OwnServerSupported ¶
OwnServerSupported refuses a server (by server_version_num) whose major is outside the range, naming the range.
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) OwnServer ¶
OwnServer reads the server's version (server_version_num) and refuses one outside the range.
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.
Source Files