@ultimat3/db 29.3.2 → 30.0.0

package/src/keyset.ts

@@ -0,0 +1,182 @@
+// Single responsibility: keyset paging for a raw read — a join the typed handle cannot express.
+// The handle's `.after()` keeps its own seek; this is the same position, carried as the column's
+// TEXT and bound back cast by kind, so a microsecond the JS `Date` would drop is never dropped.
+
+import type { Page } from '@ultimat3/core';
+import {
+  assert,
+  CursorInvalidError,
+  decodeCursor,
+  encodeCursor,
+  finiteCount,
+  pageOf,
+} from '@ultimat3/core';
+import { DbError } from './errors';
+import { join, raw, type SqlFragment, sql } from './sql';
+
+/** The kinds a position can be bound back as, each with its own cast. A closed list. */
+export type KeysetKind = 'timestamptz' | 'uuid' | 'text' | 'integer' | 'bigint';
+
+export interface KeysetKey {
+  /** The ordered expression as written in the statement: `raw('p.created_at')`, or a `sql` one. */
+  readonly column: SqlFragment;
+  readonly kind: KeysetKind;
+  readonly direction: 'asc' | 'desc';
+}
+
+export interface KeysetOptions {
+  /** This read and its arguments: a cursor from another scope is `X_CURSOR_INVALID`. */
+  readonly scope: string;
+  /** The order, last key the tiebreak. Every key must be not null on every row. */
+  readonly keys: readonly KeysetKey[];
+  /** The previous page's `nextCursor`; `null` for the first page. */
+  readonly after: string | null;
+  readonly limit: number;
+}
+
+/** A row as `page` answers it: the `_keyset_<n>` aliases `select` added are gone. */
+export type KeysetRow<Row> = Omit<Row, `_keyset_${number}`>;
+
+/** Four fragments to splice — `select …, ${k.select}`, `where ${k.where}`, `order by`, `limit`. */
+export interface Keyset {
+  readonly select: SqlFragment;
+  readonly where: SqlFragment;
+  readonly orderBy: SqlFragment;
+  /** `limit + 1`: the extra row is how `page` knows there is a next page. */
+  readonly limit: SqlFragment;
+  /** The rows the statement answered, cut to `limit`, the key aliases stripped. */
+  page<Row extends object>(rows: readonly Row[]): Page<KeysetRow<Row>>;
+}
+
+const CASTS: ReadonlyMap<KeysetKind, string> = new Map<KeysetKind, string>([
+  ['timestamptz', 'timestamptz'],
+  ['uuid', 'uuid'],
+  ['text', 'text'],
+  ['integer', 'integer'],
+  ['bigint', 'bigint'],
+]);
+
+const NULL_KEY_FIX =
+  "keyset({ keys: [{ column: sql`coalesce(p.published_at, p.created_at)`, kind: 'timestamptz', direction: 'desc' }, …] })  # or order by a not-null column";
+
+const aliasOf = (index: number): string => `_keyset_${String(index)}`;
+
+/**
+ * The scope the cursor is signed under: the caller's, plus the order itself — so a cursor minted
+ * under `desc` cannot seek an `asc` read, nor a `uuid` key be bound back as `text`. Hashed: the
+ * key expressions are the statement's, not the client's to read.
+ */
+const scopeOf = (scope: string, keys: readonly KeysetKey[]): string => {
+  const order = keys
+    .map(
+      (key) =>
+        `${key.column.text}${JSON.stringify(key.column.values.map(String))} ${key.kind} ${key.direction}`,
+    )
+    .join(',');
+  const digest = new Bun.CryptoHasher('sha256').update(`${scope}|${order}`).digest('hex');
+  return `keyset:${digest.slice(0, 16)}`;
+};
+
+const bind = (key: KeysetKey, text: string): SqlFragment =>
+  sql`${text}::${raw(CASTS.get(key.kind) ?? 'text')}`;
+
+const past = (key: KeysetKey, value: SqlFragment): SqlFragment =>
+  sql`${key.column} ${raw(key.direction === 'desc' ? '<' : '>')} ${value}`;
+
+/**
+ * Uniform direction is ONE row comparison, the shape Postgres pushes into a multicolumn index as
+ * an Index Cond. A mixed order has none, so it is the or-chain — the same split as the entity
+ * driver's `seekSql`. No null branch in either: `page` refuses a null key before it is a cursor.
+ */
+const seek = (keys: readonly KeysetKey[], position: readonly string[]): SqlFragment => {
+  const binds = (): SqlFragment[] => keys.map((key, index) => bind(key, position[index] ?? ''));
+  const [first] = keys;
+  if (first === undefined) return sql`true`;
+  if (keys.length === 1) return past(first, bind(first, position[0] ?? ''));
+  if (keys.every((key) => key.direction === first.direction)) {
+    const op = raw(first.direction === 'desc' ? '<' : '>');
+    return sql`(${join(keys.map((key) => key.column))}) ${op} (${join(binds())})`;
+  }
+  const terms = keys.map((key, index) => {
+    const equal = keys
+      .slice(0, index)
+      .map((prior, at) => sql`${prior.column} = ${bind(prior, position[at] ?? '')}`);
+    const term = past(key, bind(key, position[index] ?? ''));
+    return equal.length === 0 ? term : sql`(${join([...equal, term], ' and ')})`;
+  });
+  return sql`(${join(terms, ' or ')})`;
+};
+
+const positionOf = (cursor: string, scope: string, keys: readonly KeysetKey[]): string[] => {
+  const { key } = decodeCursor(cursor, scope);
+  if (key.length !== keys.length || !key.every((part) => typeof part === 'string')) {
+    throw new CursorInvalidError(
+      `it carries ${key.length} key values, this order needs ${keys.length}`,
+    );
+  }
+  return key as string[];
+};
+
+/** Every key of `row`, as the text the server answered — refused when one is null. */
+const keyText = (row: object, keys: readonly KeysetKey[], index: number): string[] =>
+  keys.map((key, at) => {
+    const value: unknown = Reflect.get(row, aliasOf(at));
+    if (typeof value === 'string') return value;
+    if (value === null) {
+      throw new DbError({
+        code: 'X_KEYSET_NULL_KEY',
+        cause: `row ${String(index)} holds null in keyset key ${String(at)} (${key.column.text}): a row comparison has no null order, so that row and every one like it would fall off the next page`,
+        fix: NULL_KEY_FIX,
+        meta: { key: at, row: index },
+      });
+    }
+    throw new DbError({
+      code: 'X_INVARIANT',
+      cause: `row ${String(index)} carries no ${aliasOf(at)}: the statement did not select keyset()'s keys`,
+      fix: "db().query(sql`select p.*, <k.select> from … where <k.where> order by <k.orderBy> limit <k.limit>`)  # each <…> an interpolation of keyset()'s answer",
+      meta: { key: at, row: index },
+    });
+  });
+
+const stripped = <Row extends object>(row: Row, aliases: ReadonlySet<string>): KeysetRow<Row> =>
+  Object.fromEntries(Object.entries(row).filter(([name]) => !aliases.has(name))) as KeysetRow<Row>;
+
+/**
+ * A keyset page over any statement. The key is selected as `col::text` and bound back as
+ * `$n::<kind>`: exact, no arithmetic, and the `order by` stays on the bare column, so an index on
+ * `(created_at desc, id desc)` answers it as an Index Only Scan.
+ */
+export function keyset(options: KeysetOptions): Keyset {
+  const { keys } = options;
+  assert(
+    keys.length > 0,
+    'keyset() was given no keys, so it has no order to page by',
+    "keyset({ keys: [{ column: raw('p.created_at'), kind: 'timestamptz', direction: 'desc' }, { column: raw('p.id'), kind: 'uuid', direction: 'desc' }], … })",
+  );
+  assert(
+    options.scope.length > 0,
+    'keyset() was given an empty scope, so a cursor from any other raw read would page this one',
+    "keyset({ scope: 'posts.feed', … })   # one name per read, plus its filter arguments",
+  );
+  const limit = finiteCount('keyset', 'limit', options.limit, 1);
+  const scope = scopeOf(options.scope, keys);
+  const where =
+    options.after === null ? sql`true` : seek(keys, positionOf(options.after, scope, keys));
+  return {
+    select: join(keys.map((key, at) => sql`${key.column}::text as ${raw(`"${aliasOf(at)}"`)}`)),
+    where,
+    orderBy: join(keys.map((key) => sql`${key.column} ${raw(key.direction)}`)),
+    limit: sql`${limit + 1}`,
+    page<Row extends object>(rows: readonly Row[]): Page<KeysetRow<Row>> {
+      const positions = rows.map((row, index) => keyText(row, keys, index));
+      const aliases = new Set(keys.map((_key, at) => aliasOf(at)));
+      const kept = rows.slice(0, limit).map((row) => stripped(row, aliases));
+      const last = positions[limit - 1];
+      const next =
+        rows.length > limit && last !== undefined
+          ? encodeCursor({ scope, key: last, id: '' })
+          : null;
+      return pageOf(kept, next);
+    },
+  };
+}

package/src/lifecycle-errors.ts

@@ -0,0 +1,15 @@
+// Single responsibility: the refusal `entity({ retain })` raises at declaration. Here because the
+// code is this package's — the drift step raises it too, for a partitioned table — and
+// `@ultimat3/entity` (tier 2) reaches down for it rather than registering the same code twice.
+
+import { renderFixShellArg } from '@ultimat3/core';
+import { DbError } from './errors';
+
+/** `retain` with no window, beside `appendOnly`, or otherwise unsweepable. */
+export const retainInvalid = (entity: string, reason: string): DbError =>
+  new DbError({
+    code: 'X_ENTITY_RETAIN_INVALID',
+    cause: `entity "${entity}" declares retain, and ${reason}`,
+    fix: `x db gen "retention"   # after entity('${renderFixShellArg(entity, '<entity>')}', { retain: { after: '90d', on: 'createdAt' } }) names a window and appendOnly is gone`,
+    meta: { entity },
+  });

package/src/local-settings.ts

@@ -0,0 +1,38 @@
+// Single responsibility: the framework's one writer of a transaction-local setting. Every
+// `set_config` the framework sends is this file's: parameter-bound and always local, so a value
+// ends with the transaction that set it and a pooled connection hands the next caller nothing.
+
+import type { DbClient } from './client';
+import { sql } from './sql';
+
+/** A setting's name and its value, both text — what `set_config` takes. */
+export type LocalSettings = Readonly<Record<string, string>>;
+
+/**
+ * `select set_config($1, $2, true)` per setting, on `tx`. `true` is "local": the value lives until
+ * the transaction ends, which is the only lifetime safe behind a transaction-mode pooler. Never
+ * `set`/`set local` text: those take no parameters, so a value would have to be spliced in.
+ */
+export async function setLocal(tx: DbClient, settings: LocalSettings): Promise<void> {
+  for (const [name, value] of Object.entries(settings)) {
+    await tx.execute(sql`select set_config(${name}, ${value}, true)`);
+  }
+}
+
+interface SettingRow {
+  readonly value: string | null;
+}
+
+/**
+ * What each named setting reads as now, on `tx`, for a caller that must put it back. An unset custom
+ * setting (`x.tenant` before anything set it) reads `''`, which `set_config` restores to the same
+ * "unset" every policy reads through `nullif(…, '')`.
+ */
+export async function readLocal(tx: DbClient, names: readonly string[]): Promise<LocalSettings> {
+  const prior = new Map<string, string>();
+  for (const name of names) {
+    const row = await tx.one<SettingRow>(sql`select current_setting(${name}, true) as value`);
+    prior.set(name, row?.value ?? '');
+  }
+  return Object.fromEntries(prior);
+}

package/src/marker-line.ts

@@ -0,0 +1,47 @@
+// Single responsibility: whether a migration DECLARES something with a marker line — a top-level
+// `--` comment of its own, and nothing that merely looks like one. Several markers ask this question
+// (`-- destructive: true`, `-- transaction: false`, `rolling.ts`'s), so the scan is written once.
+
+import { noiseAt } from './sql-scan';
+
+/** Whether only spaces and tabs separate `index` from the start of its line. */
+function startsLine(sql: string, index: number): boolean {
+  for (let at = index - 1; at >= 0; at -= 1) {
+    const char = sql[at];
+    if (char === '\n') return true;
+    if (char !== ' ' && char !== '\t') return false;
+  }
+  return true;
+}
+
+/**
+ * Declared only where a reader would see it: a top-level `--` line of its own, whose WHOLE text
+ * `marker` matches.
+ *
+ * A regex over the raw file matched a marker inside `/* … *\/` and inside a dollar-quoted body,
+ * where it declares nothing and no reviewer reading the diff would call it a declaration. Scanning
+ * is what tells a comment from a comment about a comment; a marker is a lexical fact, not a
+ * substring.
+ */
+export function hasMarkerLine(sql: string, marker: RegExp): boolean {
+  return markerLines(sql, marker).length > 0;
+}
+
+/** Every such line's text, in source order: a marker that names something is read off these. */
+export function markerLines(sql: string, marker: RegExp): readonly string[] {
+  const found: string[] = [];
+  let index = 0;
+  while (index < sql.length) {
+    const noise = noiseAt(sql, index);
+    if (noise === null) {
+      index += 1;
+      continue;
+    }
+    const text = sql.slice(index, noise.end);
+    if (noise.kind === 'line-comment' && startsLine(sql, index) && marker.test(text)) {
+      found.push(text);
+    }
+    index = noise.end;
+  }
+  return found;
+}

package/src/migrate-lock-retry.ts

@@ -0,0 +1,60 @@
+// Single responsibility: send one unit of a migration again when `lock_timeout` fires. A deploy that
+// dies because one reader held a table for 5 s is a wedged rollout for a thing that heals by itself.
+// `migration-step.ts` picks the unit: a transactional step whole, since it rolled back whole, and a
+// non-transactional step one statement at a time, since what already ran stays run.
+
+import { isUltimateError, jitterStatedDelay, logger, type Random } from '@ultimat3/core';
+import { DbError } from './errors';
+
+/** Retries after the first attempt, so six tries: at 3 s each, near half a minute of patience. */
+export const MIGRATION_LOCK_RETRIES = 5;
+
+export interface LockRetryPolicy {
+  readonly retries: number;
+  readonly lockTimeoutMs: number;
+  /** Seams; a test asserts the schedule rather than sleeping through it. */
+  readonly sleep?: ((ms: number) => Promise<void>) | undefined;
+  readonly random?: Random | undefined;
+}
+
+/**
+ * At least one `lockTimeoutMs` between attempts. While the ALTER queued, every query on that table
+ * queued behind it, and going straight back in would stack the same queue on a table that has had
+ * no time to serve it. Jitter upward only, so that floor is a floor.
+ */
+export async function withLockRetry(
+  id: string,
+  policy: LockRetryPolicy,
+  attempt: () => Promise<void>,
+): Promise<void> {
+  const sleep = policy.sleep ?? Bun.sleep;
+  const random = policy.random ?? Math.random;
+  for (let done = 1; ; done += 1) {
+    try {
+      await attempt();
+      return;
+    } catch (error) {
+      if (!isUltimateError(error) || error.code !== 'X_DB_LOCK_TIMEOUT') throw error;
+      const { cause, fix } = error;
+      if (done > policy.retries) {
+        throw new DbError({
+          code: 'X_DB_LOCK_TIMEOUT',
+          cause: `migration "${id}" gave up after ${done} attempts, ${policy.lockTimeoutMs} ms of lock wait each: ${cause}`,
+          fix,
+          meta: { id, attempts: done },
+          sourceError: error,
+        });
+      }
+      const waitMs = jitterStatedDelay(policy.lockTimeoutMs, policy.lockTimeoutMs, random);
+      logger.warn('ultimate migrate lock wait timed out, trying again', {
+        id,
+        attempt: done,
+        of: policy.retries + 1,
+        waitMs,
+        cause,
+        fix,
+      });
+      await sleep(waitMs);
+    }
+  }
+}

package/src/migrate-rollback.ts

@@ -1,10 +1,16 @@
 // Single responsibility: recognise a ledger an OLDER build is being rolled back onto — rows the
-// newer build applied, every one of them newer than anything this build ships — so the migrate
-// role lets a rollback through instead of failing the deploy that is trying to undo a bad one.
+// newer build applied, every one of them newer than anything this build ships — and decide whether
+// the migrate role lets that rollback through: yes over additive rows, no over destructive ones.
 
+import { renderFixShellArg } from '@ultimat3/core';
+import { isDestructiveMigration } from './destructive';
+import { DbError } from './errors';
 import type { LedgerRow, Migration } from './migration-ledger';
 import { pendingMigrations } from './migration-ledger';
 
+/** The operator's written override: the destructive migration ids they checked, comma-separated. */
+export const ROLLBACK_ALLOW_DESTRUCTIVE_ENV = 'ROLLBACK_ALLOW_DESTRUCTIVE';
+
 /** A rollback: the rows this build does not know (all newer), and the ledger it does. */
 export interface LedgerAhead {
   /** The rows a newer build applied, oldest first. Never empty. */
@@ -13,6 +19,15 @@ export interface LedgerAhead {
   readonly known: readonly LedgerRow[];
 }
 
+export interface LedgerAheadOptions {
+  /** `ROLLBACK_ALLOW_DESTRUCTIVE`'s value; read from the environment when not given. */
+  readonly allow?: string | undefined;
+}
+
+/** What the ledger records at apply: whether this migration's `up` destroys data. */
+export const destructiveBit = (migration: Migration): boolean =>
+  isDestructiveMigration(migration.up);
+
 /**
  * The ledger split, when it is exactly a rollback, else `undefined` and the caller's audit refuses
  * the unknown rows as it always has. Three conditions, all required:
@@ -25,13 +40,15 @@ export interface LedgerAhead {
  * - the build ships at least one migration. An image that lost its migrations directory is not
  *   "older than every row", and reading it as one would wave through the image that is broken.
  *
- * Nothing is applied either way: the schema the newer build left is additive over this one when
- * the release followed expand/contract (docs/ops/06-runbooks.md), and when it did not, no
- * migration this build ships could put it back.
+ * Nothing is applied either way. Over ADDITIVE rows the older build runs on the newer schema
+ * (expand/contract, docs/ops/06-runbooks.md). Over a row the newer build recorded as destructive
+ * it may not — a dropped column it still selects is the second outage — so that rollback is
+ * refused (`X_MIGRATION_ROLLBACK_DESTRUCTIVE`) unless the operator named every such row.
  */
 export function ledgerAheadOfBuild(
   ledger: readonly LedgerRow[],
   migrations: readonly Migration[],
+  options: LedgerAheadOptions = {},
 ): LedgerAhead | undefined {
   if (migrations.length === 0) return undefined;
   const shipped = new Set(migrations.map((migration) => migration.id));
@@ -40,5 +57,27 @@ export function ledgerAheadOfBuild(
   if (unknown.length === 0 || unknown.some((row) => row.id <= newest)) return undefined;
   const known = ledger.filter((row) => shipped.has(row.id));
   if (pendingMigrations(known, migrations).length > 0) return undefined;
-  return { ahead: [...unknown].sort((a, b) => (a.id < b.id ? -1 : 1)), known };
+  const ahead = [...unknown].sort((a, b) => (a.id < b.id ? -1 : 1));
+  assertRollbackSafe(ahead, options.allow ?? Bun.env[ROLLBACK_ALLOW_DESTRUCTIVE_ENV]);
+  return { ahead, known };
+}
+
+/** Every destructive row ahead must be named by the override; a null bit is not refused. */
+function assertRollbackSafe(ahead: readonly LedgerRow[], allow: string | undefined): void {
+  const named = new Set(
+    (allow ?? '')
+      .split(',')
+      .map((id) => id.trim())
+      .filter((id) => id !== ''),
+  );
+  const refused = ahead.filter((row) => row.destructive === true && !named.has(row.id));
+  if (refused.length === 0) return;
+  const ids = refused.map((row) => row.id);
+  const all = ahead.filter((row) => row.destructive === true).map((row) => row.id);
+  throw new DbError({
+    code: 'X_MIGRATION_ROLLBACK_DESTRUCTIVE',
+    cause: `the ledger holds ${ids.length} destructive migration(s) a newer build applied (${ids.join(', ')}) and this build predates them — it may read a column or table that no longer exists`,
+    fix: `x deploy --image <the newer image> --json   # roll forward; or, after checking this build runs on the newer schema: ${ROLLBACK_ALLOW_DESTRUCTIVE_ENV}=${renderFixShellArg(all.join(','), '<migration id>')} on the migrate role`,
+    meta: { refused: ids, appVersions: [...new Set(refused.map((row) => row.app_version))] },
+  });
 }

package/src/migrate.ts

@@ -3,11 +3,18 @@
 // 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 { appVersion, finiteCount, logger, renderFixShellArg } from '@ultimat3/core';
+import {
+  appVersion,
+  finiteCount,
+  isProduction,
+  logger,
+  type Random,
+  renderFixShellArg,
+} from '@ultimat3/core';
 import { baseClient, type DbClient, type DbConnection, isReservable } from './client';
-import { refuseDependentViews } from './dependent-view';
 import { expectedQueryLoop } from './expected-loop';
-import { ledgerAheadOfBuild } from './migrate-rollback';
+import { MIGRATION_LOCK_RETRIES } from './migrate-lock-retry';
+import { destructiveBit, ledgerAheadOfBuild } from './migrate-rollback';
 import { migrateConcurrent, migrationConflict, rollbackStepsInvalid } from './migration-errors';
 import type { Migration } from './migration-ledger';
 import {
@@ -18,10 +25,11 @@ import {
   pendingMigrations,
   readLedger,
 } from './migration-ledger';
+import { applyMigrationStep } from './migration-step';
 import { poolProfileFor } from './pool-profile';
+import { retireAndContractPending } from './rolling';
+import { retireAndContractTogether } from './rolling-errors';
 import { raw, sql } from './sql';
-import { statementsOf } from './statement-split';
-import { withTransaction } from './transaction';
 
 export type { LedgerRow, Migration } from './migration-ledger';
 export {
@@ -83,6 +91,13 @@ export interface MigrateOptions {
   readonly lockWaitMs?: number | undefined;
   /** `SET LOCAL lock_timeout` per migration. Defaults to the `migrate` role's profile. */
   readonly lockTimeoutMs?: number | undefined;
+  /** Attempts past the first when `lock_timeout` fires (`migrate-lock-retry.ts`). Defaults to 5. */
+  readonly lockRetries?: number | undefined;
+  /** Seams for the wait between those attempts; a test reads the schedule. */
+  readonly lockRetrySleep?: ((ms: number) => Promise<void>) | undefined;
+  readonly lockRetryRandom?: Random | undefined;
+  /** Whether a retire and its drop may land in one deploy. Defaults to core's `isProduction()`. */
+  readonly production?: boolean | undefined;
 }
 
 /**
@@ -175,43 +190,6 @@ async function withAdvisoryLock<T>(
   }
 }
 
-/**
- * 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: DbClient, 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: DbClient, 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
@@ -231,10 +209,15 @@ function migrationLockTimeoutMs(explicit: number | undefined): number {
   );
 }
 
+/** Screened beside `lockTimeoutMs`, before the advisory lock, for the reason given there. */
+const migrationLockRetries = (explicit: number | undefined): number =>
+  finiteCount('migrate', 'lockRetries', explicit ?? MIGRATION_LOCK_RETRIES, 0);
+
 export async function migrate(options: MigrateOptions): Promise<MigrationReport> {
   const client = options.client ?? baseClient();
   const appVersion = runningAppVersion(options.appVersion);
   const lockTimeoutMs = migrationLockTimeoutMs(options.lockTimeoutMs);
+  const retries = migrationLockRetries(options.lockRetries);
   const started = performance.now();
 
   return withAdvisoryLock(
@@ -261,6 +244,13 @@ export async function migrate(options: MigrateOptions): Promise<MigrationReport>
       }
 
       const pending = pendingMigrations(ledger, options.migrations);
+      // Before the first BEGIN, so nothing is half done. Only where a previous release can be
+      // running: a non-empty ledger in production. A fresh database, a template or a branch has no
+      // old pods to break and replays both freely.
+      if (ledger.length > 0 && (options.production ?? isProduction())) {
+        const pair = retireAndContractPending(pending);
+        if (pair !== undefined) throw retireAndContractTogether(pair);
+      }
       // 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
@@ -271,27 +261,31 @@ export async function migrate(options: MigrateOptions): Promise<MigrationReport>
           const done: AppliedMigration[] = [];
           for (const migration of pending) {
             const at = performance.now();
-            await withTransaction(
-              async (tx) => {
-                await setLockTimeout(tx, lockTimeoutMs);
-                // Before the first statement, never after the failure: a view compiled against a
-                // column this script retypes is `0A000` from the server with the view named only in
-                // a DETAIL field nothing prints, surfaced as "cannot reach the database". Costs one
-                // text scan and no round trip on a migration that retypes nothing, which is nearly
-                // all of them (`dependent-view.ts`).
-                await refuseDependentViews(tx, migration.up);
-                await applyScript(tx, migration.up);
+            // Inside a transaction, or — a migration marked `-- transaction: false` — statement by
+            // statement outside one (`migration-step.ts`). Either way the ledger row is written
+            // only after the last statement succeeded, on the lock's own session.
+            await applyMigrationStep(session, {
+              id: migration.id,
+              up: migration.up,
+              script: migration.up,
+              lockTimeoutMs,
+              lockRetry: {
+                retries,
+                sleep: options.lockRetrySleep,
+                random: options.lockRetryRandom,
+              },
+              // The bit an OLDER build reads on a rollback (`migrate-rollback.ts`): recorded here,
+              // by the build that knows the SQL, because the one rolled back to never sees it.
+              record: async (client) => {
                 const durationMs = Math.round(performance.now() - at);
-                await tx.execute(sql`
-                insert into ${raw(LEDGER_TABLE)} (id, name, checksum, app_version, duration_ms)
+                await client.execute(sql`
+                insert into ${raw(LEDGER_TABLE)}
+                  (id, name, checksum, app_version, duration_ms, destructive)
                 values (${migration.id}, ${migration.name}, ${migrationChecksum(migration)},
-                        ${appVersion}, ${durationMs})
+                        ${appVersion}, ${durationMs}, ${destructiveBit(migration)})
               `);
               },
-              // 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,
@@ -327,6 +321,8 @@ export interface RollbackOptions {
   readonly lockWaitMs?: number | undefined;
   /** `SET LOCAL lock_timeout` per reversal. Defaults to the `migrate` role's profile. */
   readonly lockTimeoutMs?: number | undefined;
+  /** Attempts past the first when `lock_timeout` fires. Defaults to 5, as `migrate`'s does. */
+  readonly lockRetries?: number | undefined;
 }
 
 /** Reverse the newest `steps` applied migrations. `x db rollback`. */
@@ -337,6 +333,7 @@ export async function rollback(options: RollbackOptions): Promise<readonly strin
   // "one fewer", so an unvalidated count reverses migrations nobody asked about.
   if (!Number.isSafeInteger(steps) || steps < 1) throw rollbackStepsInvalid(steps);
   const lockTimeoutMs = migrationLockTimeoutMs(options.lockTimeoutMs);
+  const retries = migrationLockRetries(options.lockRetries);
   const known = new Map(options.migrations.map((migration) => [migration.id, migration]));
 
   // The same lock `migrate` takes, because the race is the same one: a rollback reversing the id a
@@ -369,17 +366,18 @@ export async function rollback(options: RollbackOptions): Promise<readonly strin
                   'and roll back there — its down SQL exists nowhere else',
               );
             }
-            await withTransaction(
-              async (tx) => {
-                await setLockTimeout(tx, lockTimeoutMs);
-                // Both directions: a reversal retypes the same column back, and a view created
-                // since the migration applied blocks it exactly as one created before would.
-                await refuseDependentViews(tx, migration.down);
-                await applyScript(tx, migration.down);
-                await tx.execute(sql`delete from ${raw(LEDGER_TABLE)} where id = ${row.id}`);
+            // The marker on `up` governs `down` too: the reversal of a concurrent build is a
+            // concurrent drop, refused inside a transaction just the same.
+            await applyMigrationStep(session, {
+              id: migration.id,
+              up: migration.up,
+              script: migration.down,
+              lockTimeoutMs,
+              lockRetry: { retries },
+              record: async (client) => {
+                await client.execute(sql`delete from ${raw(LEDGER_TABLE)} where id = ${row.id}`);
               },
-              { client: session },
-            );
+            });
             reverted.push(row.id);
           }
           return reverted;