@ultimat3/db 1.1.0 → 2.0.0

package/src/index.ts

@@ -2,6 +2,7 @@
 // `@ultimat3/auth`, `@ultimat3/entity`, `@ultimat3/jobs` and the CLI are written against this
 // list, so anything not here is an implementation detail and may change.
 
+export { statementAttribution, withStatementAttribution } from './attribution';
 export type { BranchInfo, BranchOptions, DropBranchOptions, ReapOptions } from './branch';
 export {
   assertBranchName,
@@ -26,17 +27,29 @@ export {
   createPostgresClient,
   db,
   isReservable,
+  POOL_MAX_ENV,
   POOL_PROFILES,
   poolProfileFor,
   setDbClient,
 } from './client';
+export type { DestructiveKind, DestructiveStatement } from './destructive';
+export {
+  DESTRUCTIVE_CAUSE,
+  DESTRUCTIVE_MARKER,
+  destructiveStatements,
+  hasDestructiveMarker,
+  isDestructive,
+} from './destructive';
 export type { DriftDifference, DriftKind, DriftOptions, DriftReport } from './drift';
 export {
+  appTables,
   assertNoDrift,
   checkDrift,
+  declaredSchema,
   diffSchema,
   driftError,
   expectedSchema,
+  FRAMEWORK_TABLE_PREFIX,
 } from './drift';
 export type { DbErrorCode, DbErrorInit } from './errors';
 export {
@@ -48,12 +61,20 @@ export {
   dbDrift,
   dbNotImplemented,
   dbUnavailable,
+  driverError,
   identifierUnsafe,
+  migrateConcurrent,
   migrationConflict,
+  migrationDestructive,
   migrationIrreversible,
-  readonlyViolation,
+  migrationSnapshotMissing,
+  multipleStatements,
+  poolAcquireTimeout,
+  poolMaxInvalid,
+  serializationExhausted,
   sqlUnsafe,
 } from './errors';
+export { expectedQueryLoop, expectedQueryLoopReason } from './expected-loop';
 export type { RecordedStatement, RecordingClient, StubResponse } from './fake';
 export { createRecordingClient } from './fake';
 export type {
@@ -61,15 +82,9 @@ export type {
   EntityDescriptionLike,
   GeneratedMigration,
   GenerateOptions,
-  ParsedIndex,
-} from './generate';
-export {
-  generateMigration,
-  migrationStamp,
-  parseIndexName,
-  slugify,
-  snapshotOf,
+  IndexDescriptionLike,
 } from './generate';
+export { generateMigration, migrationStamp, slugify, snapshotOf } from './generate';
 export type {
   ColumnDescription,
   ForeignKeyDescription,
@@ -91,8 +106,11 @@ export {
   auditLedger,
   checksumOf,
   ensureLedger,
+  isLedgerMissing,
   LEDGER_TABLE,
   MIGRATION_LOCK_KEY,
+  MIGRATION_LOCK_POLL_MS,
+  MIGRATION_LOCK_WAIT_MS,
   migrate,
   migrationChecksum,
   pendingMigrations,
@@ -100,6 +118,8 @@ export {
   rollback,
   runningAppVersion,
 } from './migrate';
+export type { StatementAttribution, StatementEvent, StatementObserver } from './observe';
+export { setStatementObserver, statementObserver } from './observe';
 export type {
   PgliteClient,
   PgliteDriver,
@@ -117,13 +137,19 @@ export {
 } from './pglite';
 export type { PgliteBranchInfo, PgliteBranchOptions } from './pglite-branch';
 export { branchPglite, pgliteBranchDir } from './pglite-branch';
-export type { MutationVerdict, ReadOnlyOptions } from './readonly';
-export { assertReadOnly, inspectStatement, readOnly, stripSqlNoise } from './readonly';
 export type { ReadOnlyQueryOptions, ReadOnlyQueryResult } from './readonly-query';
 export { READONLY_TIMEOUT_MS, readOnlyQuery } from './readonly-query';
 export type { ReadOnlyRoleOptions } from './readonly-role';
 export { ensureReadOnlyRole, grantReadOnlySql, READONLY_ROLE } from './readonly-role';
+export { snapshotJson } from './snapshot-json';
+export { parseSnapshot } from './snapshot-parse';
 export type { SqlFragment } from './sql';
 export { identifier, isSqlFragment, join, literal, raw, sql } from './sql';
+export { stripSqlNoise } from './sql-noise';
+export type { DbSqlStateCode } from './sqlstate';
+export { DB_SQLSTATE_CODES, isRetryableState, SQLSTATE, sqlState, sqlStateCode } from './sqlstate';
+export { statementFingerprint, statementKind, statementVerb } from './statement-shape';
+export { STATEMENT_ATTRIBUTE } from './statement-span';
+export { statementsOf } from './statement-split';
 export type { DbTx, IsolationLevel, TransactionOptions } from './transaction';
 export { beginStatement, currentTx, withTransaction } from './transaction';

package/src/introspect.ts

@@ -17,9 +17,18 @@ export interface ColumnDescription {
 
 export interface IndexDescription {
   readonly name: string;
+  /** Physical columns in **index key order** — the order the planner sorts by, never `attnum`. */
   readonly columns: readonly string[];
   readonly unique: boolean;
   readonly primary: boolean;
+  /**
+   * Partial index predicate as SQL, `null` when the index covers every row. The catalog returns
+   * its own rewriting of the expression (`(deleted_at IS NULL)`), never the author's spelling, so
+   * this is readable and comparable to *itself* — never to a snapshot's text. See `drift.ts`.
+   */
+  readonly where: string | null;
+  /** `desc` only when every key column is descending; `null` is Postgres' own default. */
+  readonly order: 'asc' | 'desc' | null;
 }
 
 export interface ForeignKeyDescription {
@@ -65,6 +74,8 @@ interface IndexRow {
   readonly is_unique: boolean;
   readonly is_primary: boolean;
   readonly columns: readonly string[];
+  readonly predicate: string | null;
+  readonly descending: boolean;
 }
 
 interface ForeignKeyRow {
@@ -90,37 +101,50 @@ export async function introspect(options: IntrospectOptions = {}): Promise<Schem
     order by table_name, ordinal_position
   `);
 
+  // Ordered by the index's own key position, never by `attnum`: `indkey` IS the order the planner
+  // sorts by, and a composite index on `(created_at, org_id)` whose columns were declared the
+  // other way round came back reversed — a description that reads correct and compares wrong.
+  // `indnkeyatts` drops INCLUDE payload columns, which are stored, not keyed.
   const indexes = await client.query<IndexRow>(sql`
     select
       t.relname as table_name,
       i.relname as index_name,
       ix.indisunique as is_unique,
       ix.indisprimary as is_primary,
-      array_agg(a.attname order by a.attnum) as columns
+      pg_get_expr(ix.indpred, ix.indrelid) as predicate,
+      array_agg(a.attname order by k.ord) as columns,
+      bool_and((ix.indoption[k.ord - 1] & 1) = 1) as descending
     from pg_class t
     join pg_namespace n on n.oid = t.relnamespace
     join pg_index ix on ix.indrelid = t.oid
     join pg_class i on i.oid = ix.indexrelid
-    join pg_attribute a on a.attrelid = t.oid and a.attnum = any(ix.indkey)
-    where n.nspname = ${schema} and t.relkind = 'r'
-    group by t.relname, i.relname, ix.indisunique, ix.indisprimary
+    cross join lateral unnest(ix.indkey::smallint[]) with ordinality as k(attnum, ord)
+    join pg_attribute a on a.attrelid = t.oid and a.attnum = k.attnum
+    where n.nspname = ${schema} and t.relkind = 'r' and k.ord <= ix.indnkeyatts
+    group by t.relname, i.relname, ix.indisunique, ix.indisprimary, ix.indpred, ix.indrelid
     order by t.relname, i.relname
   `);
 
+  // `conkey` and `confkey` are unnested TOGETHER, by shared ordinality: they are two halves of one
+  // ordered pairing, and matching each independently with `= any(...)` is a cross product — a
+  // two-column key came back as four source columns against four referenced ones, duplicated and
+  // misaligned. Ordered by `k.ord` (the constraint's own key position), never by `attnum`, for the
+  // same reason `indkey` orders the index query: `references t (y, x)` is not `references t (x, y)`.
   const foreignKeys = await client.query<ForeignKeyRow>(sql`
     select
       src.relname as table_name,
       c.conname as constraint_name,
-      array_agg(sa.attname order by sa.attnum) as columns,
+      array_agg(sa.attname order by k.ord) as columns,
       tgt.relname as referenced_table,
-      array_agg(ta.attname order by ta.attnum) as referenced_columns,
+      array_agg(ta.attname order by k.ord) as referenced_columns,
       c.confdeltype as on_delete
     from pg_constraint c
     join pg_class src on src.oid = c.conrelid
     join pg_class tgt on tgt.oid = c.confrelid
     join pg_namespace n on n.oid = src.relnamespace
-    join pg_attribute sa on sa.attrelid = src.oid and sa.attnum = any(c.conkey)
-    join pg_attribute ta on ta.attrelid = tgt.oid and ta.attnum = any(c.confkey)
+    cross join lateral unnest(c.conkey, c.confkey) with ordinality as k(src_attnum, tgt_attnum, ord)
+    join pg_attribute sa on sa.attrelid = src.oid and sa.attnum = k.src_attnum
+    join pg_attribute ta on ta.attrelid = tgt.oid and ta.attnum = k.tgt_attnum
     where c.contype = 'f' and n.nspname = ${schema}
     group by src.relname, c.conname, tgt.relname, c.confdeltype
     order by src.relname, c.conname
@@ -149,6 +173,8 @@ export function buildSchema(
         columns: [...row.columns],
         unique: row.is_unique,
         primary: row.is_primary,
+        where: row.predicate,
+        order: row.descending ? ('desc' as const) : null,
       }))
       .sort(byName);
     return {

package/src/migrate.ts

@@ -3,17 +3,39 @@
 // app-version fence is the `migrate` role's contract — a pod must refuse to migrate a database
 // another build already owns, because the alternative is two schemas racing during a rollout.
 
-import { baseClient, type DbClient } from './client';
-import { migrationConflict } from './errors';
+import { appVersion } from '@ultimat3/core';
+import {
+  baseClient,
+  type DbClient,
+  type DbConnection,
+  isReservable,
+  poolProfileFor,
+} from './client';
+import { migrateConcurrent, migrationConflict } from './errors';
+import { expectedQueryLoop } from './expected-loop';
 import type { SchemaDescription } from './introspect';
 import { raw, sql } from './sql';
-import { withTransaction } from './transaction';
+import { SQLSTATE, sqlState } from './sqlstate';
+import { statementsOf } from './statement-split';
+import { type DbTx, withTransaction } from './transaction';
 
 export const LEDGER_TABLE = 'x_migrations';
 
 /** Stable, arbitrary: every Ultimate migrator contends on this one key. */
 export const MIGRATION_LOCK_KEY = 4_919_202_607;
 
+/**
+ * How long a migrator waits for the lock before refusing. A deploy hook must fail rather than
+ * hang: `pg_advisory_lock` blocks with no timeout, so a wedged predecessor held `helm upgrade
+ * --wait` inside one statement with nothing in the logs and `backoffLimit` never reached. Long
+ * enough that a genuinely slow migration ahead of us is waited out, short enough that a stuck one
+ * becomes an exit code inside a deploy window.
+ */
+export const MIGRATION_LOCK_WAIT_MS = 60_000;
+
+/** One poll per half-second: cheap against a lock that is usually free on the first try. */
+export const MIGRATION_LOCK_POLL_MS = 500;
+
 export interface Migration {
   /** Sort key and primary key. `20260726120000_add_publish_at`. */
   readonly id: string;
@@ -56,6 +78,10 @@ export interface MigrateOptions {
   readonly client?: DbClient | undefined;
   /** Skip the advisory lock. Only `x db branch` does this, against a private database. */
   readonly lock?: boolean | undefined;
+  /** How long to wait for the lock before `X_MIGRATE_CONCURRENT`. Defaults to 60s. */
+  readonly lockWaitMs?: number | undefined;
+  /** `SET LOCAL lock_timeout` per migration. Defaults to the `migrate` role's profile. */
+  readonly lockTimeoutMs?: number | undefined;
 }
 
 export function checksumOf(text: string): string {
@@ -66,8 +92,13 @@ export function migrationChecksum(migration: Migration): string {
   return migration.checksum ?? checksumOf(migration.up);
 }
 
+/**
+ * Core's, never a second read of the key: `x_migrations.app_version` and `x_backfills.app_version`
+ * are two durable columns an operator reads side by side, and a package defaulting `APP_VERSION`
+ * its own way would put two names on one build.
+ */
 export function runningAppVersion(explicit?: string | undefined): string {
-  return explicit ?? process.env['APP_VERSION'] ?? 'dev';
+  return explicit ?? appVersion();
 }
 
 export async function ensureLedger(client: DbClient): Promise<void> {
@@ -83,6 +114,22 @@ export async function ensureLedger(client: DbClient): Promise<void> {
   `);
 }
 
+/**
+ * Whether `error` is "the ledger table does not exist" and nothing else.
+ *
+ * Everything else — a permission denied, a server in recovery, a timeout — is a failure to read the
+ * ledger, not an empty one, and a caller treating the two alike reports every migration as pending
+ * against a database it cannot see.
+ *
+ * The SQLSTATE comes from `sqlState()` and from nowhere else: this function used to read
+ * `sourceError.code` itself, which is the SQLSTATE on PGlite and the literal string
+ * `ERR_POSTGRES_SERVER_ERROR` on `Bun.SQL`, so it answered `false` for a genuinely missing ledger
+ * on every production driver. One reader, one answer (axiom 1).
+ */
+export function isLedgerMissing(error: unknown): boolean {
+  return sqlState(error) === SQLSTATE.undefinedTable;
+}
+
 export async function readLedger(client: DbClient): Promise<readonly LedgerRow[]> {
   return client.query<LedgerRow>(sql`
     select id, name, checksum, applied_at, app_version, duration_ms
@@ -108,7 +155,12 @@ export function auditLedger(
     throw migrationConflict(
       `the ledger records migration "${first.id}" applied by app version "${first.app_version}" ` +
         `but this build is "${appVersion}" and does not ship it`,
-      `x db status --json   # then deploy app version "${first.app_version}", or roll the ledger`,
+      // `x db status` has never existed — the subcommands are gen, migrate, reset, studio, branch
+      // and backfill — and this is one of the two errors most likely to fire during a real deploy.
+      // A `fix:` is copied and run verbatim, so it names the ledger read that works anywhere psql
+      // does, and the one edit that resolves the disagreement.
+      `deploy app version "${first.app_version}" — or, if that build is gone, drop its row: ` +
+        `psql "$DATABASE_URL" -c "delete from ${LEDGER_TABLE} where id = '${first.id}'"`,
     );
   }
 
@@ -134,95 +186,252 @@ export function pendingMigrations(
     .filter((migration) => !applied.has(migration.id));
 }
 
+/**
+ * Hold the migration lock on **one** session for the whole of `fn`, which runs on that session.
+ *
+ * `pg_advisory_lock` is scoped to a Postgres session, not to a statement, so taking it on a pooled
+ * handle locks whichever connection the pool lent for that one statement and then hands the
+ * session back. Two things follow, and both were live: the unlock lands on a *different*
+ * connection, answers `false` and leaves the lock held until that backend dies — so the next
+ * migrator waits forever rather than for the migration; and the locking session, now idle for the
+ * whole run, is closed by the pool's idle timeout (`migrate`'s is 10s), which releases the lock
+ * mid-migration and lets a second deploy in. `ROLE=migrate` hid the first half by accident — its
+ * pool is `max: 1`, so every statement found the same connection. No other role and no test has
+ * that.
+ *
+ * `fn` receives the pinned session and must run every statement on it, for the same `max: 1`
+ * reason read the other way: a statement sent to the pool while the pin is held waits for a
+ * connection that cannot come back until the migration blocking on it has finished.
+ */
+
+/**
+ * Take the lock, or refuse — never block forever.
+ *
+ * `pg_advisory_lock` has no timeout, and that is a deploy outage waiting for its trigger: a
+ * predecessor OOM-killed on a network partition keeps its backend, and with it the lock, for hours.
+ * The new `ROLE=migrate` pod then sits inside one statement printing nothing, `helm upgrade --wait`
+ * blocks on a pod that is `Running` and healthy, and because the job never *fails*, `backoffLimit`
+ * never fires. `pg_try_advisory_lock` answers immediately, so the wait becomes ours to bound and
+ * the wedge becomes an exit code carrying the lock key and the pid to terminate.
+ *
+ * Declared as an expected loop: a poll is a loop the framework argued for, and a diagnostic that
+ * reported it would teach an author to ignore the ones nobody argued for.
+ */
+async function acquireLock(session: DbClient, waitMs: number): Promise<void> {
+  const started = performance.now();
+  await expectedQueryLoop(
+    'the migration lock is polled, not waited on, so a wedged migrator fails a deploy instead of hanging it',
+    async () => {
+      for (;;) {
+        const row = await session.one<{ locked: boolean }>(
+          sql`select pg_try_advisory_lock(${MIGRATION_LOCK_KEY}) as locked`,
+        );
+        if (row?.locked === true) return;
+        const remaining = waitMs - (performance.now() - started);
+        if (remaining <= 0) {
+          throw migrateConcurrent(MIGRATION_LOCK_KEY, Math.round(performance.now() - started));
+        }
+        await Bun.sleep(Math.min(MIGRATION_LOCK_POLL_MS, remaining));
+      }
+    },
+  );
+}
+
 async function withAdvisoryLock<T>(
   client: DbClient,
   enabled: boolean,
-  fn: () => Promise<T>,
+  waitMs: number,
+  fn: (session: DbClient) => Promise<T>,
 ): Promise<T> {
-  if (!enabled) return fn();
-  await client.execute(sql`select pg_advisory_lock(${MIGRATION_LOCK_KEY})`);
+  if (!enabled) return fn(client);
+  // Held by a `using` declaration, like every other pin in this package: the lock is taken after
+  // the guard exists, so a rejecting `pg_advisory_lock` gives the connection back too.
+  using pinned: DbConnection | undefined = isReservable(client)
+    ? await client.reserve()
+    : undefined;
+  const session: DbClient = pinned ?? client;
+  await acquireLock(session, waitMs);
   try {
-    return await fn();
+    return await fn(session);
   } finally {
-    await client
+    // Best-effort, and only here: an unlock that rejects would mask the failure that ended the
+    // migration, and it can only reject on a session that is already broken — whose locks Postgres
+    // drops when it ends. It runs before the pin is disposed, so the unlock reaches the session
+    // that took the lock.
+    await session
       .execute(sql`select pg_advisory_unlock(${MIGRATION_LOCK_KEY})`)
       .catch(() => undefined);
   }
 }
 
+/**
+ * A migration's `up` and `down` are **scripts**, and one send is one statement — because the two
+ * drivers disagree about anything else. PGlite's `query()` is the extended protocol always and
+ * answers `cannot insert multiple commands into a prepared statement`; `Bun.SQL.unsafe` degrades
+ * to the simple protocol when no value is bound and applies the same script, which is a fact about
+ * bun 1.3.14 and not a contract. `createTable` emits the table *and* every index it carries, and
+ * `x dev` runs on the embedded driver, so the refusing side was the common path.
+ *
+ * No `expectedQueryLoop` of its own: both call sites already run inside the one declared for the
+ * migration loop, and nesting here would replace that reason with a narrower one for no gain. An
+ * empty script sends nothing at all, which is how a no-op migration reaches its ledger row.
+ */
+async function applyScript(tx: DbTx, script: string): Promise<void> {
+  for (const statement of statementsOf(script)) await tx.execute(raw(statement));
+}
+
+/**
+ * Bound how long this migration will queue behind a lock it cannot take.
+ *
+ * `alter table … add column` needs `ACCESS EXCLUSIVE`. A long `SELECT` holding `ACCESS SHARE`
+ * makes it wait — and because Postgres' lock queue is FIFO, **every subsequent query on that table
+ * queues behind the ALTER**. The `migrate` profile runs `statement_timeout = 0` deliberately, so
+ * without this the migrator waits forever and the app is down on one table for as long as the
+ * reporting query runs. `lock_timeout` bounds the *wait* alone and never the work, which is why it
+ * is the right knob where `statement_timeout` is not.
+ *
+ * `SET LOCAL`, inside the migration's own transaction: it reverts at COMMIT, so a value chosen for
+ * DDL never leaks onto the session the ledger insert or the next migration runs on. A 0 disables
+ * it, exactly like `statementTimeoutMs`. The failure it produces is `55P03`, typed as
+ * `X_DB_LOCK_TIMEOUT` by `driverError` with the `pg_stat_activity` read as its fix.
+ */
+async function setLockTimeout(tx: DbTx, lockTimeoutMs: number): Promise<void> {
+  if (lockTimeoutMs <= 0) return;
+  // `SET LOCAL` takes no parameter placeholder, and the value is a validated integer of ours.
+  await tx.execute(raw(`SET LOCAL lock_timeout = ${Math.round(lockTimeoutMs)}`));
+}
+
+/**
+ * `migrate` role's profile whatever role is running, because the statement is a migration whatever
+ * process issues it: `x db migrate` from a laptop, `x dev`'s boot and `ROLE=migrate` all take the
+ * same `ACCESS EXCLUSIVE` locks against the same tables.
+ */
+function migrationLockTimeoutMs(explicit: number | undefined): number {
+  return explicit ?? poolProfileFor('migrate').lockTimeoutMs;
+}
+
 export async function migrate(options: MigrateOptions): Promise<MigrationReport> {
   const client = options.client ?? baseClient();
   const appVersion = runningAppVersion(options.appVersion);
+  const lockTimeoutMs = migrationLockTimeoutMs(options.lockTimeoutMs);
   const started = performance.now();
 
-  return withAdvisoryLock(client, options.lock !== false, async () => {
-    await ensureLedger(client);
-    const ledger = await readLedger(client);
-    auditLedger(ledger, options.migrations, appVersion);
-
-    const pending = pendingMigrations(ledger, options.migrations);
-    const applied: AppliedMigration[] = [];
-    for (const migration of pending) {
-      const at = performance.now();
-      await withTransaction(
-        async (tx) => {
-          await tx.execute(raw(migration.up));
-          const durationMs = Math.round(performance.now() - at);
-          await tx.execute(sql`
-            insert into ${raw(LEDGER_TABLE)} (id, name, checksum, app_version, duration_ms)
-            values (${migration.id}, ${migration.name}, ${migrationChecksum(migration)},
-                    ${appVersion}, ${durationMs})
-          `);
+  return withAdvisoryLock(
+    client,
+    options.lock !== false,
+    options.lockWaitMs ?? MIGRATION_LOCK_WAIT_MS,
+    async (session) => {
+      await ensureLedger(session);
+      const ledger = await readLedger(session);
+      auditLedger(ledger, options.migrations, appVersion);
+
+      const pending = pendingMigrations(ledger, options.migrations);
+      // A statement per migration and a transaction per migration is the point, not an N+1 to batch:
+      // one failed `up` must leave the ledger describing exactly the migrations that did run, and a
+      // batch commits or loses all of them together. Declared here so a diagnostic reports the loops
+      // nobody argued for and stays quiet about this one.
+      const applied = await expectedQueryLoop(
+        'each migration applies in its own transaction, so a failure leaves an exact ledger',
+        async () => {
+          const done: AppliedMigration[] = [];
+          for (const migration of pending) {
+            const at = performance.now();
+            await withTransaction(
+              async (tx) => {
+                await setLockTimeout(tx, lockTimeoutMs);
+                await applyScript(tx, migration.up);
+                const durationMs = Math.round(performance.now() - at);
+                await tx.execute(sql`
+                insert into ${raw(LEDGER_TABLE)} (id, name, checksum, app_version, duration_ms)
+                values (${migration.id}, ${migration.name}, ${migrationChecksum(migration)},
+                        ${appVersion}, ${durationMs})
+              `);
+              },
+              // The lock's own session: a migration applied on another connection is not covered by
+              // the lock at all, and on `ROLE=migrate` there is no other connection to apply it on.
+              { client: session },
+            );
+            done.push({
+              id: migration.id,
+              name: migration.name,
+              durationMs: Math.round(performance.now() - at),
+            });
+          }
+          return done;
         },
-        { client },
       );
-      applied.push({
-        id: migration.id,
-        name: migration.name,
-        durationMs: Math.round(performance.now() - at),
-      });
-    }
-
-    return {
-      applied,
-      skipped: ledger.map((row) => row.id),
-      durationMs: Math.round(performance.now() - started),
-      appVersion,
-    };
-  });
+
+      return {
+        applied,
+        skipped: ledger.map((row) => row.id),
+        durationMs: Math.round(performance.now() - started),
+        appVersion,
+      };
+    },
+  );
 }
 
 export interface RollbackOptions {
   readonly migrations: readonly Migration[];
   readonly client?: DbClient | undefined;
   readonly steps?: number | undefined;
+  /** Skip the advisory lock. Only `x db branch` does this, against a private database. */
+  readonly lock?: boolean | undefined;
+  /** How long to wait for the lock before `X_MIGRATE_CONCURRENT`. Defaults to 60s. */
+  readonly lockWaitMs?: number | undefined;
+  /** `SET LOCAL lock_timeout` per reversal. Defaults to the `migrate` role's profile. */
+  readonly lockTimeoutMs?: number | undefined;
 }
 
 /** Reverse the newest `steps` applied migrations. `x db rollback`. */
 export async function rollback(options: RollbackOptions): Promise<readonly string[]> {
   const client = options.client ?? baseClient();
   const steps = options.steps ?? 1;
-  const ledger = await readLedger(client);
+  const lockTimeoutMs = migrationLockTimeoutMs(options.lockTimeoutMs);
   const known = new Map(options.migrations.map((migration) => [migration.id, migration]));
-  const targets = [...ledger].reverse().slice(0, steps);
-  const reverted: string[] = [];
 
-  for (const row of targets) {
-    const migration = known.get(row.id);
-    if (migration === undefined) {
-      throw migrationConflict(
-        `migration "${row.id}" is in the ledger but not in this build, so its down SQL is unknown`,
-        `x db status --json   # deploy the build that shipped "${row.id}" and roll back there`,
+  // The same lock `migrate` takes, because the race is the same one: a rollback reversing the id a
+  // migrator is applying leaves a ledger that describes neither, and the ledger read below decides
+  // what to reverse — outside the lock it can be stale before the first `down` runs.
+  return withAdvisoryLock(
+    client,
+    options.lock !== false,
+    options.lockWaitMs ?? MIGRATION_LOCK_WAIT_MS,
+    async (session) => {
+      const ledger = await readLedger(session);
+      const targets = [...ledger].reverse().slice(0, steps);
+
+      // The same deliberate loop as `migrate`, read backwards: one transaction per `down`, newest
+      // first, so a `down` that fails leaves every migration before it still applied and recorded.
+      return expectedQueryLoop(
+        'each migration reverses in its own transaction, newest first, so a failure stops exactly there',
+        async () => {
+          const reverted: string[] = [];
+          for (const row of targets) {
+            const migration = known.get(row.id);
+            if (migration === undefined) {
+              throw migrationConflict(
+                `migration "${row.id}" is in the ledger but not in this build, so its down SQL is unknown`,
+                // Same reason as `auditLedger`'s: `x db status` does not exist. The `down` SQL only
+                // exists in the build that shipped it, so the fix is the read that names that build.
+                `psql "$DATABASE_URL" -c "select id, app_version from ${LEDGER_TABLE} ` +
+                  `order by id desc limit 5"   # deploy the build that shipped "${row.id}", ` +
+                  'and roll back there — its down SQL exists nowhere else',
+              );
+            }
+            await withTransaction(
+              async (tx) => {
+                await setLockTimeout(tx, lockTimeoutMs);
+                await applyScript(tx, migration.down);
+                await tx.execute(sql`delete from ${raw(LEDGER_TABLE)} where id = ${row.id}`);
+              },
+              { client: session },
+            );
+            reverted.push(row.id);
+          }
+          return reverted;
+        },
       );
-    }
-    await withTransaction(
-      async (tx) => {
-        await tx.execute(raw(migration.down));
-        await tx.execute(sql`delete from ${raw(LEDGER_TABLE)} where id = ${row.id}`);
-      },
-      { client },
-    );
-    reverted.push(row.id);
-  }
-  return reverted;
+    },
+  );
 }