sql

type Checker ¶

type Checker interface {
	// Check probes the database under a bounded budget and returns nil when
	// it answered. A non-nil error is always typed and never carries the
	// connection string.
	Check(ctx context.Context) error
}

Checker reports whether the database is reachable. Implementations MUST be safe for concurrent use.

type Deferrer ¶ added in v0.11.0

type Deferrer interface {
	// Defer holds fn until the transaction ctx carries for this transactor
	// commits, and reports true.
	//
	// The held functions run once, in the order they were held, on the
	// goroutine that commits, after the commit and before the outermost
	// Transact returns. A rollback drops them, and so does the rollback of
	// the savepoint they were held in; a savepoint that is released hands
	// them to the scope around it. A panic in one reaches the caller of the
	// outermost Transact after the commit stood, and the functions held after
	// it do not run.
	//
	// Defer reports false and holds nothing when ctx carries no open
	// transaction of this transactor. There is no commit to wait for, so fn
	// is the caller's again, usually to run at once. A nil fn holds nothing
	// and gets the same answer.
	Defer(ctx context.Context, fn func()) (held bool)
}

Deferrer is an ADR 0039 sibling of Transactor: a transactor that holds a function until the transaction a context carries has committed. Discover it by type assertion; the SDK's own transactor implements it.

It is how an effect that must not happen for work that is rolled back — a store's write hooks, a message, a mail — waits for the commit (ADR 0139).

type Dialect ¶

type Dialect uint8

Dialect names a SQL engine whose savepoint grammar, placeholder syntax and advisory-lock mechanism this SDK knows exactly.

The set is CLOSED and small on purpose. Every feature this domain adds — a savepoint, a `CREATE TABLE IF NOT EXISTS`, an advisory lock — is spelled differently by each engine, and there is no portable subset that covers all three. So the domain refuses a dialect it cannot spell AT CONSTRUCTION, by name, rather than generating SQL that will fail at the first savepoint of the first nested transaction on a production database (ADR 0055 §D4).

The zero value is DialectUnknown and is not usable: it is what an unset configuration field looks like, and reading it as "probably Postgres" is how a MySQL deployment discovers the difference in production (ADR 0031).

const (
	// DialectUnknown is the unusable zero value.
	DialectUnknown Dialect = iota
	// DialectPostgres is PostgreSQL 9.1+ (and wire-compatible engines that
	// implement pg_advisory_lock, e.g. CockroachDB advertises the function
	// but the caller must verify it is a real lock before claiming this).
	DialectPostgres
	// DialectMySQL is MySQL 5.7+ / MariaDB 10.x with InnoDB.
	DialectMySQL
	// DialectSQLite is SQLite 3.6.8+.
	DialectSQLite
)

func ParseDialect(name string) (dialect Dialect, err error)

func (d Dialect) String() string

func (d Dialect) SupportsAdvisoryLock() bool

func (d Dialect) Valid() bool

type Executor ¶

type Executor interface {
	// ExecContext runs a statement that returns no rows.
	ExecContext(ctx context.Context, query string, args ...any) (stdsql.Result, error)
	// QueryContext runs a statement that returns rows. The caller closes them.
	QueryContext(ctx context.Context, query string, args ...any) (*stdsql.Rows, error)
	// QueryRowContext runs a statement expected to return at most one row.
	QueryRowContext(ctx context.Context, query string, args ...any) *stdsql.Row
}

Executor is the surface a statement runs against: a pool, a connection, or a transaction. Implementations MUST be safe for concurrent use, with the documented exception of a transaction-scoped executor, which is confined to its scope (see internal/service/sql).

The method set is a strict SUBSET of what *sql.DB, *sql.Tx and *sql.Conn already expose, so all three satisfy this port with no adapter. That is the point: the SDK is not wrapping database/sql, it is naming the part of it a caller should be allowed to reach.

It is FROZEN at three methods. pkg/v1/sql aliases it, so under ADR 0039 a fourth method would break every downstream double at compile time with no deprecation window. New capabilities arrive as SIBLING interfaces the implementation is type-asserted for — Preparer is the first.

What is deliberately absent ¶

There is no Commit, no Rollback and no Begin. A function that receives an Executor therefore CANNOT end the transaction it was handed: the method does not exist, so the mistake does not compile. Ownership of a transaction stays with the Transactor that opened it (ADR 0055 §D3).

type Joiner ¶ added in v0.11.0

type Joiner interface {
	// Join returns the executor a statement issued under ctx runs on.
	//
	// When ctx carries a transaction THIS transactor opened, that is the
	// executor of the innermost scope ctx names, and inTx is true. It is
	// valid only while that scope runs and refuses afterwards: a context
	// that outlived its transaction must not fall back to the pool, where
	// its statements would run outside the transaction they were written
	// for.
	//
	// When ctx carries none — no transaction, or only another transactor's —
	// it is the pool, outside any transaction, and inTx is false.
	Join(ctx context.Context) (ex Executor, inTx bool)
}

Joiner is an ADR 0039 sibling of Transactor: a transactor that says where a statement issued under a context runs. Discover it by type assertion; the SDK's own transactor implements it.

It is what lets a callee JOIN the transaction its caller opened instead of opening a second one. A second transaction takes a second connection, does not see the caller's uncommitted writes, and under a pool of one waits forever for the connection its own caller holds (ADR 0139).

type MigrationValue ¶

type MigrationValue struct {
	// Version orders the migration. It must be non-zero and unique within one
	// set: zero is reserved as "before every migration", the value Down takes
	// to reverse everything.
	//
	// Any strictly-increasing scheme works; a UTC timestamp (20260910143000)
	// is the conventional one because two branches developed in parallel then
	// merge without colliding.
	Version uint64
	// Name is the human label recorded in the version table. It must be
	// non-empty: a schema history whose rows say only "42" is a schema
	// history nobody can read during an incident.
	Name string
	// Up applies the change. Required.
	Up Step
	// Down reverses it. Required — and [Irreversible] is how a caller says
	// "this one cannot be reversed" OUT LOUD.
	//
	// A nil Down is refused rather than accepted as "irreversible", because
	// "I forgot the reversal" and "there is no reversal" are the same nil and
	// only one of them is a defect. The same rule core/lifecycle applies to a
	// nil Stop, for the same reason.
	Down Step
}

MigrationValue is one versioned schema change and its reversal.

The SDK does NOT own a migration FILE FORMAT, a directory layout, or a naming convention, and it ships no example directory. A migration is a value the consumer constructs, because the moment the SDK reads a directory it has invented a convention every consumer must adopt and no consumer asked for (ADR 0055 §D8). Where the statements come from — a Go literal, an embed.FS, a generator — is the caller's decision and none of the SDK's business.

The zero value is not runnable and is refused at construction.

func (m MigrationValue) Validate() error

type Migrator ¶

type Migrator interface {
	// Plan reports what Up would apply, in the order it would apply it,
	// WITHOUT applying anything and without taking the migration lock. It is
	// the dry run: a read of the version table and a set difference.
	Plan(ctx context.Context) ([]MigrationValue, error)
	// Up applies every pending migration in ascending version order, each in
	// its own transaction, under the migration lock.
	Up(ctx context.Context) error
	// Down reverses every applied migration whose version is STRICTLY GREATER
	// than target, in descending order, each in its own transaction, under the
	// migration lock. Down(ctx, 0) reverses everything.
	Down(ctx context.Context, target uint64) error
}

Migrator applies an ordered, versioned set of MigrationValue to a schema, under mutual exclusion. Implementations MUST be safe for concurrent use, and MUST be safe against a SECOND PROCESS running the same migrations at the same instant.

IFACE-PLUGIN: the concrete runner stays unexported behind its constructor in internal/service/sql.

type Preparer ¶

type Preparer interface {
	// PrepareContext compiles a statement. The caller closes it.
	PrepareContext(ctx context.Context, query string) (*stdsql.Stmt, error)
}

Preparer is the first ADR 0039 sibling of Executor: an executor that can also prepare a statement for repeated execution. Discover it by type assertion rather than by widening Executor.

*sql.DB, *sql.Tx and *sql.Conn all satisfy it; a transaction-scoped executor does too, and the prepared statement it returns is bound to that transaction and dies with it.

type Step ¶

type Step func(ctx context.Context, ex Executor) error

Step is one direction of a migration: the statements that move the schema.

A FUNCTION port, for the same reason TxFunc is: one behaviour, so a named func IS the contract, and a func type cannot grow a method (ADR 0039).

It receives the SAME Executor the surrounding transaction runs on, which is what makes a migration and its version-table row commit together.

type Transactor ¶

type Transactor interface {
	// Transact runs fn inside a transaction and commits when fn returns nil.
	//
	// If ctx already carries a transaction opened by THIS Transactor, fn runs
	// inside a SAVEPOINT of that transaction instead of a new one, and opts
	// must be the zero value — a savepoint cannot change isolation or
	// read-only-ness, so asking for either is refused with [NestedIsolation]
	// rather than silently ignored (ADR 0055 §D5).
	//
	// A panic inside fn is NOT recovered: the deferred rollback still runs,
	// and the panic reaches the caller with its original stack.
	Transact(ctx context.Context, opts TxOptionsValue, fn TxFunc) error
}

Transactor owns transactions. Implementations MUST be safe for concurrent use.

It is FROZEN at one method, and the options travel in a struct rather than as a second method, precisely so the port never needs a sibling for "Transact, but read-only" (ADR 0039).

IFACE-PLUGIN: the concrete manager stays unexported behind its constructor in internal/service/sql.

type TxFunc ¶

type TxFunc func(ctx context.Context, ex Executor) error

TxFunc is the unit of work a Transactor runs inside a transaction.

It is a FUNCTION port, the shape internal/core/CLAUDE.md already admits for resilience.Operation, scheduler.Job and lifecycle.Start: one behaviour, so a named func IS the contract. ADR 0039 is satisfied structurally — a func type cannot grow a method at all.

ctx is the transaction-scoped context. Passing it on is what lets a callee join THIS transaction rather than open a second one, and what lets a nested Transactor.Transact become a savepoint instead of a deadlock against the transaction its own caller is holding.

Returning nil commits (or releases the savepoint). Returning an error rolls back (or rolls back to the savepoint) and the error is returned to the caller VERBATIM, so errors.Is keeps working across the boundary.

ex is valid ONLY for the duration of the call. Using it afterwards is refused with a typed error rather than left to database/sql's ErrTxDone.

type TxOptionsValue ¶

type TxOptionsValue struct {
	// Isolation is the transaction isolation level. The zero value
	// (sql.LevelDefault) defers to the driver.
	Isolation stdsql.IsolationLevel
	// ReadOnly asks the engine to refuse writes. Not every driver enforces
	// it; those that do not report an error at Begin rather than accepting
	// writes silently, which is why this is passed through rather than
	// emulated.
	ReadOnly bool
}

TxOptionsValue parameterises ONE transaction. It is a value, not a manager setting, because isolation is a property of the unit of work and not of the pool it runs on.

The zero value is a working configuration: the driver's default isolation level, read-write. That is the only non-arbitrary default available — every engine defines its own default level and picking one here would silently change the semantics of an existing application on migration (ADR 0031's clamp side, where the default needs no explanation because it is the database's own).

It is deliberately a struct rather than two extra method parameters so Transactor stays frozen at one method: a new option is a new FIELD, which breaks nobody, where a new method breaks every downstream double (ADR 0039).

func (o TxOptionsValue) IsZero() bool

func (o TxOptionsValue) StdOptions() *stdsql.TxOptions