sql

func ChecksumOf ¶ added in v0.27.0

func ChecksumOf(stmts ...string) string

ChecksumOf is the fingerprint coresql.MigrationValue.Checksum records for a migration built from stmts: SHA-256 over the statements in order, each preceded by its length in bytes as an 8-byte big-endian unsigned integer, rendered as 64 lowercase hexadecimal digits.

The length prefix is what makes the fingerprint the statements' and not their concatenation's: "CREATE TABLE a" then "(x INT)" and "CREATE TABLE a(x INT)" alone are different migrations and get different checksums. Write it beside the steps it describes, from the same statements, so the two cannot drift:

ddl := []string{"CREATE TABLE accounts (id BIGINT PRIMARY KEY)"}
m := sql.Migration{Version: 1, Name: "accounts",
	Up: sql.Statements(ddl...), Down: sql.Statements("DROP TABLE accounts"),
	Checksum: sql.ChecksumOf(ddl...)}

func Classify ¶ added in v0.27.0

func Classify(err error) bool

Classify is the SDK's coresql.Transient: true for a failure the database documents as "run the transaction again", read from the methods drivers expose rather than from a driver this package would have to import.

A SQLSTATE of 40001 (serialization failure) or 40P01 (deadlock detected), read through a SQLState() string method — pgx's and lib/pq's errors offer one —, and a SQLite result code whose primary code is 5 (BUSY) or 6 (LOCKED), extended forms such as 517 (BUSY_SNAPSHOT) included, read through a Code() int method — modernc.org/sqlite's errors offer one. Every error the chain joins or wraps is read, so a verdict joined beside the driver's error, or a Withheld, still answers.

A context's end is never transient, whatever else the chain carries. MySQL's deadlock (1213) and lock-wait timeout (1205) are not read here: go-sql-driver exposes them as fields, not methods, so a MySQL connector composes its own reading with this one.

func Each ¶ added in v0.27.0

func Each[T any](rows *stdsql.Rows, scan func(*stdsql.Rows) (T, error)) iter.Seq2[T, error]

Each iterates rows, scanning each with scan, and closes rows when the iteration ends — at the last row, at the first failure, or when the loop stops early. A failure — scan's, rows.Err's or the close's — is yielded once, as the last element, beside T's zero value:

rows, err := ex.QueryContext(ctx, "SELECT id, name FROM accounts")
if err != nil {
	return err
}
for account, err := range sql.Each(rows, scanAccount) {
	if err != nil {
		return err
	}
	use(account)
}

It is the Next/Scan/Err/Close loop every caller writes, written once; it scans nothing itself, since mapping a row is the caller's (ADR 0055 §D1). A nil rows yields nothing.

func FileLockSQL ¶

func FileLockSQL(table string) string

FileLockSQL renders the statement that makes a SQLite transaction take the database file's write lock at once, where BEGIN — which database/sql sends as SQLite's deferred form — takes none.

It is a DELETE that matches no row. SQLite starts the write transaction a write statement needs when the statement STARTS, before its WHERE clause is weighed, so the lock is taken and nothing is changed (ADR 0140). Two transactions take it: the migration runner's, naming its version table — the one table it knows exists at that point, since it creates it first in the same transaction — and the queue's lease, naming its queue's table before its first read, so the read cannot answer from a snapshot the update after it would be refused for.

table is interpolated exactly as given — bare, as the runner's validated version table is, or already quoted, as the queue's is — and must have been validated at construction, which is the whole defence of an interpolated identifier.

func InsertRows ¶ added in v0.27.0

func InsertRows(ctx context.Context, ex coresql.Executor, d coresql.Dialect, into InsertSpec, rows [][]any) (inserted int64, err error)

InsertRows inserts rows into into.Table, into.PerStatement rows per statement, on ex, and returns how many rows the statements report inserted.

Each statement reads INSERT INTO table (cols) VALUES (…), (…), its bind markers spelled by d and numbered across the statement. into.Table and into.Columns are interpolated exactly as given — bare, or already quoted with coresql.Dialect.QuoteIdent — and must have been validated by the caller, which is the whole defence of an interpolated identifier; the values are always bound.

into.PerStatement is clamped to what d's engine binds in one statement — 999 parameters on SQLite, the oldest ceiling it ships with, and 65535 on PostgreSQL and MySQL — divided by the number of columns; a non-positive one takes that ceiling. A row whose width is not the number of columns, no columns at all or a dialect that is not Valid is refused with coresql.ConfigInvalid before any statement runs. A statement's failure is returned verbatim, with the count of rows the statements before it inserted; run InsertRows in a transaction for all or none.

func NewChecker ¶

func NewChecker(cfg Config) (probe coresql.Checker, err error)

NewChecker returns a bounded liveness probe over cfg.DB.

Like NewTransactor it applies cfg.Pool, so a process whose only SQL port is a health check still gets its pool policy installed.

func NewMigrator ¶

func NewMigrator(cfg Config, mig MigrateConfig) (runner coresql.Migrator, err error)

NewMigrator returns the migration runner for cfg.DB.

Every run is mutually exclusive across processes, and the lock is one its holder's death releases: the session's advisory lock on PostgreSQL and MySQL (ADR 0055 §D7), the database file's write lock on SQLite (ADR 0140). Running unlocked is never offered as a fallback: a runner that silently drops mutual exclusion is at its most dangerous in exactly the situation it exists for — two instances of a deployment starting together.

func NewRetrying ¶ added in v0.27.0

func NewRetrying(tm coresql.Transactor, cfg RetryConfig) (manager coresql.Transactor, err error)

NewRetrying returns a transactor that runs a ROOT transaction of tm again when it fails on an error cfg.Transient calls transient, up to cfg.Attempts runs, waiting cfg.Backoff's curve on cfg.Clock between two.

Each attempt is a whole transaction of tm: a new BEGIN, the unit of work from its start, and the commit or the rollback tm decides — so what the unit of work held with Defer is dropped with each attempt that rolled back and runs once, after the commit that stood, and what it held with OnAbort runs after each rollback. The unit of work MUST therefore be safe to run more than once: its effects outside the transaction belong in Defer, as ADR 0055 asks of a retried transaction.

A NESTED call — one whose context already carries a transaction of tm, opened through this transactor or through tm itself — joins it as tm does, and is never run again on its own: a savepoint cannot be retried without the transaction around it. A failure that is not transient, and a context that ended, return at once. When the budget is spent the last attempt's error is returned joined with coresql.TxRetriesExhausted, whose "attempts" field says how many ran.

The transactor offers coresql.Joiner, coresql.Deferrer and coresql.Aborter exactly when tm offers all three, forwarding each to tm. A nil tm is refused with coresql.ConfigInvalid.

func NewTransactor ¶

func NewTransactor(cfg Config) (manager coresql.Transactor, err error)

NewTransactor returns the transaction manager for cfg.DB.

It applies cfg.Pool to the caller's *sql.DB. That is a side effect on a value the caller owns, and it is deliberate: a pool policy that has to be installed by a second call is a pool policy someone will forget, and the consequence of forgetting it (unlimited connections, connections that live forever) lands on the database rather than on this process.

func Observe ¶ added in v0.27.0

func Observe(c driver.Connector, obs coresql.StatementObserver) driver.Connector

Observe returns c with obs told about every statement the connections it opens send: each Exec, Query and Prepare on a connection, each Exec and Query of a statement it prepared, and each transaction's BEGIN, COMMIT and ROLLBACK — savepoints included, which travel as statements. A caller opens its pool over it and hands that pool to this package as it always did:

pool := stdsql.OpenDB(sql.Observe(connector, sql.SlowQueries(time.Second, log, clock.System)))

The observer receives the SQL text as written, cut to MaxObservedQuery bytes, and never an argument or a row. A query's end is told when its rows close, with how many were read. A call the driver skips with driver.ErrSkip — database/sql then prepares the statement, and the prepared calls are told in turn — ends with that error; the two observers this package ships ignore it.

The connections keep every optional interface database/sql reads — a ping, a session reset, a validity check, a driver's own argument checker — answering as the driver's own do, and declining as database/sql's defaults would where the driver has none. A nil obs is no wrapper: c is returned as it is (ADR 0031).

func SlowQueries ¶ added in v0.27.0

func SlowQueries(threshold time.Duration, log corelogger.Logger, clk clock.Clock) coresql.StatementObserver

SlowQueries returns an observer that logs, at Warn, each statement that took threshold or longer, timed on clk: its kind, its SQL text, its duration, the rows it read or affected, and — when it failed — the driver error's class as Withheld renders it, never its text. A statement under the threshold logs nothing, and costs one reading of the clock at each end. A non-positive threshold logs every statement; a nil clk is clock.System.

func Statements ¶

func Statements(stmts ...string) coresql.Step

Statements returns a coresql.Step that runs stmts in order on the transaction's executor, stopping at the first failure.

This is the smallest helper that is genuinely useful and deliberately not a file loader. Reading a directory would mean inventing a filename grammar (`0001_name.up.sql`? `V1__name.sql`?), a statement splitter, and a rule for what a `;` inside a string literal means — three conventions the SDK would impose on every consumer and none of them asked for (ADR 0055 §D8).

Each statement is sent as its own Exec rather than as one semicolon-joined string, because multi-statement execution is a per-driver capability that several disable by default, and because a failure then names the statement that failed by its position in the slice.

The text is the caller's own and is never bound: a migration's DDL cannot be parameterised on any engine. That is exactly why migrations must not be built from user input, and why this helper takes a variadic of literals rather than a template.

func Traced ¶ added in v0.27.0

func Traced(tracer coretrace.Tracer) coresql.StatementObserver

Traced returns an observer that opens one client span per statement under the span ctx carries, named "sql " and the kind, with the SQL text as db.query.text, and ends it when the statement ends, with the rows as db.response.returned_rows and an error status — the driver error's class as Withheld renders it — when it failed.