store

package
v0.1.21 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Oct 21, 2026 License: MIT Imports: 6 Imported by: 0

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

View Source
const (
	ConstraintUnique     = "unique"
	ConstraintForeignKey = "foreign_key"
	ConstraintNotNull    = "not_null"
	ConstraintCheck      = "check"
	ConstraintExclusion  = "exclusion"
)

Constraint kinds a ConstraintError reports.

Variables

View Source
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.

View Source
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.

View Source
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.

View Source
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.

View Source
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.

View Source
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.

View Source
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.

View Source
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.

View Source
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

func Iter(rows Rows) iter.Seq2[Row, error]

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

func IterNamed(rows Rows, names []string) iter.Seq2[Row, error]

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

type ConstraintError struct {
	Kind       string
	Constraint string
	Columns    []string
	Err        error
}

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

func (d *PreparedDB) ExecContext(ctx context.Context, query string, args ...any) (Result, error)

ExecContext implements DB.

func (*PreparedDB) QueryContext

func (d *PreparedDB) QueryContext(ctx context.Context, query string, args ...any) (Rows, error)

QueryContext implements DB.

type Preparer

type Preparer interface {
	PrepareContext(ctx context.Context, query string) (Prepared, error)
}

Preparer is an optional DB capability. Existing DB fakes need not implement it.

type Result

type Result struct {
	LastInsertID int64
	RowsAffected int64
}

Result summarizes a write execution.

type Row

type Row = map[string]any

Row is a single decoded result row keyed by column name.

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

type TxBeginner interface {
	BeginTx(ctx context.Context, opts *TxOptions) (Tx, error)
}

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.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL