@ultimat3/db 23.0.0 → 24.0.0

package/src/drift-errors.ts

@@ -10,9 +10,9 @@ import { DbError } from './errors';
 import { shellInertIdentifier } from './sql';
 
 /**
- * The contract's pinned wording. Mirror of `@ultimat3/entity`'s `dbDrift()` — keep in sync; that
- * one screens the column through the same `@ultimat3/db` export, so the two lines are the same
- * text on both sides of the tier seam.
+ * The contract's pinned wording, and the ONE definition of it: `@ultimat3/entity` carried a second
+ * `dbDrift()` held in step by a comment and a test, deleted `As of 2026-10-02`. Drift is this
+ * package's to raise.
  *
  * The column name is the CATALOG's, so it is data: whoever can add a column picks the text that
  * lands here, and `x db gen "add C"` puts it inside SHELL DOUBLE QUOTES, where `$(…)` and a

package/src/drift-findings.ts

@@ -1,19 +1,13 @@
-// Single responsibility: what a schema difference is CALLED and what its `fix:` line says — one
-// constructor per `DriftKind`, and nothing that compares anything. Split out of `drift.ts` at the
-// 500-line ceiling, along the seam that file already drew: comparison decides *whether* two
-// schemas disagree, and this decides how the disagreement reads.
-//
-// The rendered `X_DB_DRIFT` output is byte-for-byte pinned by the framework contract and
-// duplicated in `@ultimat3/entity` — do not reword a `cause` without changing both.
-//
-// Two rules run through every one of them. A `fix:` is a command the reader can RUN: `x db
-// migrate` where the migration has not been applied, and the statement itself where it has, since
-// re-running the migrator applies nothing a ledger row already claims. And a difference names the
-// declared side's own spelling, never the catalog's, because the catalog's is Postgres' rewriting.
+// Single responsibility: what a schema difference is CALLED and what its `fix:` says — one
+// constructor per `DriftKind`, and nothing that compares anything (`drift.ts` decides whether two
+// schemas disagree). A `fix:` is ONE command a shell runs, and a difference names the declared
+// side's spelling, never the catalog's — which is Postgres' rewriting.
 
-import { onDeleteRule, rebuildForeignKey } from './foreign-key';
+import { psqlCommand } from './dependent-view';
+import { addForeignKey, dropForeignKey, onDeleteRule } from './foreign-key';
 import type { CheckDescription, ForeignKeyDescription } from './introspect';
 import type { Migration } from './migrate';
+import { addPrimaryKey, dropPrimaryKey } from './primary-key';
 import { shellInertIdentifier } from './sql';
 
 export type DriftKind =
@@ -25,6 +19,7 @@ export type DriftKind =
   | 'unknown-schema'
   | 'missing-index'
   | 'changed-index'
+  | 'changed-primary-key'
   | 'missing-check'
   | 'missing-foreign-key'
   | 'changed-foreign-key'
@@ -45,6 +40,66 @@ export interface DriftReport {
   readonly differences: readonly DriftDifference[];
 }
 
+const RE_CHECK = 'then x db migrate, which re-checks';
+
+/** `set not null` is refused by the server while a row still holds NULL, and says so here. */
+const NULLS_FIRST = `refused while a row holds NULL there, so backfill those first; ${RE_CHECK}`;
+
+const CARRIES =
+  'a name in this difference carries a backtick, a dollar sign, a quote, a backslash or whitespace';
+
+const UNSPELLABLE = `${CARRIES}, so no statement here can spell it`;
+
+/**
+ * `x db migrate` is the fix where a migration has not been applied. Where it has, re-running the
+ * migrator applies nothing a ledger row already claims, so the fix is the statement itself —
+ * a repair made against THIS database, as one line a shell runs: the statement is `psql`'s
+ * argument (`psqlCommand`), never bare DDL beside a `#` — `#` is not a comment to Postgres and
+ * `alter` is not a program to a shell, so neither reader could run that line (axiom 4). Against
+ * this database and never "in a new migration": drift means this database left the migrations,
+ * and a migration would re-apply the repair to every database that is already right.
+ */
+const repair = (path: string, statements: string, note = RE_CHECK): string =>
+  `${psqlCommand(`${path}${statements}`)}   # ${note}`;
+
+/**
+ * The same repair when no statement can be written — a name the screen refuses. Still a command
+ * that runs: a psql session, with what to do in it as the comment. No name rides in it, hostile
+ * or not; the `cause` holds them, and nobody pastes a cause.
+ */
+export const byHand = (steps: string, why = UNSPELLABLE): string =>
+  `psql "$DATABASE_URL"   # ${steps}, \\q, ${RE_CHECK} — ${why}`;
+
+/** The schema Postgres resolves an unqualified name in when a session sets nothing. */
+const DEFAULT_SCHEMA = 'public';
+
+/**
+ * What puts a statement in the schema its table was READ from: nothing for the default one — the
+ * text every app has seen — and `set search_path` in the same psql word for any other, so the
+ * table, and every table the statement references, resolves there. A `psql "$DATABASE_URL"`
+ * session starts on its own search_path: unqualified, `alter table "posts"` for a table in
+ * `tenant_a` fails, or lands on a same-named table in `public`. `null` for a schema no statement
+ * can spell.
+ */
+const pathTo = (schema: string): string | null => {
+  if (schema === DEFAULT_SCHEMA) return '';
+  const name = shellInertIdentifier(schema);
+  return name === null ? null : `set search_path = ${name}; `;
+};
+
+/** A table as a psql PATTERN or a statement outside `pathTo`: qualified unless the default schema. */
+const qualified = (schema: string, table: string): string | null => {
+  const name = shellInertIdentifier(table);
+  if (name === null) return null;
+  if (schema === DEFAULT_SCHEMA) return name;
+  const space = shellInertIdentifier(schema);
+  return space === null ? null : `${space}.${name}`;
+};
+
+/** Every name inert in a shell AND writable as an identifier — the one screen, asked of each. */
+const spellable = (names: readonly string[]): boolean =>
+  names.every((name) => shellInertIdentifier(name) !== null);
+
 /**
  * The one `fix:` here whose second layer no quoting closes. `x db gen "add C"` puts the column
  * inside SHELL DOUBLE QUOTES, where `$(…)` and a backtick substitute before `x` is reached at all
@@ -93,13 +148,16 @@ export function missingColumn(table: string, column: string): DriftDifference {
  *
  * `x db gen` is deliberately not the fix: it diffs types and indexes and has never emitted a
  * `set not null`, so naming it would send a reader to a command that generates an empty migration.
+ * The fix is the statement, run against this database (`repair`).
  */
 export function changedColumn(
+  schema: string,
   table: string,
   column: string,
   liveNullable: boolean,
 ): DriftDifference {
   const clause = liveNullable ? 'set not null' : 'drop not null';
+  const path = pathTo(schema);
   const relation = shellInertIdentifier(table);
   const attribute = shellInertIdentifier(column);
   return {
@@ -109,16 +167,15 @@ export function changedColumn(
     cause: liveNullable
       ? `table "${table}" allows NULL in column "${column}" that migrations declare not null`
       : `table "${table}" forbids NULL in column "${column}" that migrations declare nullable`,
-    // Both identifiers are the catalog's, so both go through the one screen. A refusal names the
-    // column as the thing it could not spell, which is what tells this line apart from
-    // `missingCheck`'s refusal in a report that carries both.
+    // Both identifiers are the catalog's, so both go through the one screen.
     fix:
-      relation === null || attribute === null
-        ? `${clause} on the column named in this difference, in a new migration, then ` +
-          'x db migrate — its table or column name carries a backtick, a dollar sign, a quote, ' +
-          'a backslash or whitespace, so no statement here can spell it'
-        : `alter table ${relation} alter column ${attribute} ${clause};   # in a new migration` +
-          (liveNullable ? ' — backfill the existing NULLs first' : ''),
+      path === null || relation === null || attribute === null
+        ? byHand(`alter column … ${clause} on the column this difference names`)
+        : repair(
+            path,
+            `alter table ${relation} alter column ${attribute} ${clause};`,
+            liveNullable ? NULLS_FIRST : RE_CHECK,
+          ),
   };
 }
 
@@ -134,22 +191,32 @@ export function changedColumn(
  * the relation is already there, and `x db migrate` then accepts a table its own SQL creates), or
  * nothing owns it and it should not be in this schema. No migration PATH is named: where an app
  * keeps its migrations is the CLI's fact, not this package's.
+ *
+ * Two repairs and one line, so the line leads with the command neither repair can skip — `\\d` on
+ * the table, through `psqlCommand`, which is what keeps a `'` in the name inside its shell word.
  */
-export function unexpectedTable(table: string): DriftDifference {
-  const name = shellInertIdentifier(table);
+export function unexpectedTable(schema: string, table: string): DriftDifference {
+  const name = qualified(schema, table);
+  // The comment repeats the name only when it holds no `'`: a shell that does not read `#` as a
+  // comment (interactive zsh, by default) would open a quote on one. The command is safe either
+  // way — `psqlCommand` escapes it inside its own word.
+  const spoken = name === null || name.includes("'") ? 'this table' : name;
   return {
     kind: 'unexpected-table',
     table,
     column: null,
     cause: `table "${table}" is not present in any migration`,
+    // The command is the harmless one — it SHOWS the table, which either repair needs first — and
+    // the two repairs are its comment.
     fix:
       name === null
-        ? 'claim it in a migration with create table if not exists, or drop it by hand — its ' +
-          'table name carries a backtick, a dollar sign, a quote, a backslash or whitespace, so ' +
-          'no statement here can spell it'
-        : `put a create table if not exists ${name} (…) statement in a migration — x db migrate ` +
-          'then accepts a table its own SQL creates — or, if nothing owns it, run ' +
-          `drop table ${name}; inside psql "$DATABASE_URL"`,
+        ? byHand(
+            `inspect the table this difference names with \\d, then claim it in a migration ` +
+              'with create table if not exists or drop it',
+          )
+        : `${psqlCommand(`\\d ${name}`)}   # nothing declares it: put create table if not exists ` +
+          `${spoken} (…) in a migration, then x db migrate — or, if nothing owns it, run ` +
+          `drop table ${spoken}; here`,
   };
 }
 
@@ -176,7 +243,7 @@ export function unknownSchema(migrations: readonly Migration[]): DriftDifference
   // id off the file and derives the name from it — so whoever can add a file to the migrations
   // directory picks what a reader pastes, and `$(…)` and a backtick substitute before `git` or `x`
   // is reached. The same screen `unexpectedColumn` and `changedColumn` already ran, on the one
-  // finding in this file that skipped it. Degraded to prose rather than escaped: a glob is not an
+  // finding in this file that skipped it. Degraded to a read-only command rather than escaped: a glob is not an
   // identifier and a migration description is not one either, so neither has a quoted form that
   // makes a hostile name safe. An EMPTY id is inert by construction and keeps its glob — that is
   // "no migrations at all", not a name this function refused to spell.
@@ -196,10 +263,10 @@ export function unknownSchema(migrations: readonly Migration[]): DriftDifference
     fix: spellable
       ? `git checkout -- "*${id}.snapshot.json"   # or, if it was never written: ` +
         `delete migration "${id}" and rerun x db gen "${name}"`
-      : 'restore the .snapshot.json committed beside the newest migration, or delete that ' +
-        'migration and rerun x db gen with its description — the migration named in this ' +
-        "difference's cause carries a backtick, a dollar sign, a quote, a backslash or " +
-        'whitespace in its file name, so no command here can spell it',
+      : 'git status --short -- "*.snapshot.json"   # shows the sidecar that is gone: git ' +
+        'checkout it, or delete that migration and rerun x db gen with its description — the ' +
+        "migration named in this difference's cause carries a backtick, a dollar sign, a " +
+        'quote, a backslash or whitespace in its file name, so no command here can spell it',
   };
 }
 
@@ -232,12 +299,17 @@ export function changedIndex(table: string, index: string, detail: string): Drif
  * 'published'::text])))` — so a text comparison reports drift on a correct database forever, and
  * normalising it is an expression parser competing with the server's. Presence is not text.
  *
- * The `fix` is the statement, not `x db migrate`: the migration that declares this constraint is
- * already in the ledger, so re-running the migrator applies nothing. Same reasoning as
- * `changedColumn` and `changedForeignKey` — the declared side holds the author's own spelling of
- * the predicate, which is what makes an executable fix possible at all.
+ * The `fix` is the statement (`repair`), not `x db migrate`: the migration that declares this
+ * constraint is already in the ledger, so re-running the migrator applies nothing. Same reasoning
+ * as `changedColumn` and `changedForeignKey` — the declared side holds the author's own spelling
+ * of the predicate, which is what makes an executable fix possible at all.
  */
-export function missingCheck(table: string, check: CheckDescription): DriftDifference {
+export function missingCheck(
+  schema: string,
+  table: string,
+  check: CheckDescription,
+): DriftDifference {
+  const path = pathTo(schema);
   const relation = shellInertIdentifier(table);
   const constraint = shellInertIdentifier(check.name);
   return {
@@ -245,23 +317,18 @@ export function missingCheck(table: string, check: CheckDescription): DriftDiffe
     table,
     column: null,
     cause: `table "${table}" is missing check constraint "${check.name}" that migrations declare`,
-    // The command rides on the same line as the statement, and not only because `check` is a
-    // banned advice word the `errors` gate demands a command beside: writing the migration is half
-    // the repair and applying it is the other half, and `changedColumn`'s bare `# in a new
-    // migration` leaves the second half to be guessed.
-    //
     // Both NAMES go through the one screen; the EXPRESSION deliberately does not, and cannot. It
     // is a predicate, so no screen could accept `status in ('draft', 'published')` and reject a
     // second statement — and it is the DECLARED side's own text, out of the author's migration,
-    // where both names are the catalog's and a sidecar's. Narrower than "this line is safe", and
-    // it is the honest claim.
+    // where both names are the catalog's and a sidecar's. What `psqlCommand` does close is the
+    // shell layer: the statement is one single-quoted word, so nothing in the predicate expands.
     fix:
-      relation === null || constraint === null
-        ? 'add the constraint named in this difference back in a new migration, then ' +
-          'x db migrate — its table or constraint name carries a backtick, a dollar sign, a ' +
-          'quote, a backslash or whitespace, so no statement here can spell it'
-        : `alter table ${relation} add constraint ${constraint} ` +
-          `check (${check.expression});   # in a new migration, then x db migrate`,
+      path === null || relation === null || constraint === null
+        ? byHand('add the check constraint this difference names back')
+        : repair(
+            path,
+            `alter table ${relation} add constraint ${constraint} check (${check.expression});`,
+          ),
   };
 }
 
@@ -282,26 +349,109 @@ export function missingForeignKey(table: string, key: ForeignKeyDescription): Dr
  * — reported apart from `missing-foreign-key` because it is a different repair: the constraint is
  * there, and what changed is what happens to the child rows.
  *
- * The `fix` is the pair, not `x db migrate`: a rule cannot be altered in place, `add constraint`
- * alone is `42710` on a name already taken, and no `x db gen` diff emits either statement, so
- * naming a command would send a reader to one that generates an empty migration. Same reasoning
- * as `changedColumn`.
+ * The `fix` is the pair (`repair`), not `x db migrate`: a rule cannot be altered in place, `add
+ * constraint` alone is `42710` on a name already taken, and no `x db gen` diff emits either
+ * statement. Same reasoning as `changedColumn`.
+ *
+ * `held` is the **live catalog's** and `declared` is a `.snapshot.json`'s, so every name is
+ * screened and the two writers are ASKED whether they can write the pair — never a second copy of
+ * their rules beside them. `identifier()` refuses a name holding a quote, a space or a backslash
+ * and `addForeignKey` refuses an `on delete` rule Postgres does not have: right for DDL this
+ * package SENDS, wrong for a `fix:`. `diffSchema` is documented pure and total, so a pair it
+ * cannot write is a psql session and a sentence, never a throw.
+ *
+ * The CAUSE names the constraint the database holds, whatever it is called: a refused name is out
+ * of the command, and the cause is where a reader still finds which key this is.
  */
 export function changedForeignKey(
+  schema: string,
   table: string,
   declared: ForeignKeyDescription,
   held: ForeignKeyDescription,
 ): DriftDifference {
   const rule = onDeleteRule(held.onDelete);
+  const rebuilt = (): string => {
+    const steps =
+      'drop the foreign key this difference names and add it back with the on delete rule ' +
+      'migrations declare';
+    const names = [
+      table,
+      held.name,
+      declared.name,
+      declared.referencedTable,
+      ...declared.columns,
+      ...declared.referencedColumns,
+    ];
+    const path = pathTo(schema);
+    if (path === null || !spellable(names)) return byHand(steps);
+    try {
+      return repair(path, `${dropForeignKey(table, held.name)} ${addForeignKey(table, declared)}`);
+    } catch {
+      return byHand(steps, 'the rule migrations declare is not one Postgres has');
+    }
+  };
   return {
     kind: 'changed-foreign-key',
     table,
     column: null,
     cause:
-      `foreign key on "${table}" (${declared.columns.join(', ')}) to ` +
+      `foreign key "${held.name}" on "${table}" (${declared.columns.join(', ')}) to ` +
       `"${declared.referencedTable}" ` +
       `${rule === null ? 'declares no on delete rule' : `is on delete ${rule}`}, not what ` +
       'migrations declare',
-    fix: `${rebuildForeignKey(table, declared, held)}   # in a new migration`,
+    fix: rebuilt(),
+  };
+}
+
+const PRIMARY_KEY_BY_HAND = byHand(
+  'drop the primary key this database holds, add the one migrations declare',
+  `${CARRIES} or is too long, so no statement here can spell it`,
+);
+
+const keyText = (columns: readonly string[]): string =>
+  columns.length === 0 ? 'no primary key' : `primary key (${columns.join(', ')})`;
+
+/**
+ * The two sides key the table differently — a different column list, a different ORDER, or a key
+ * on one side only. Its own kind rather than `changed-index` on `<table>_pkey`: that finding's fix
+ * is `x db migrate`, and the migration declaring this key is already in the ledger, so re-running
+ * the migrator applies nothing.
+ *
+ * The fix is ONE command a shell runs — the pair as `psql`'s argument (`repair`).
+ *
+ * `held` is the constraint the DATABASE holds — the live primary index's name, which is the
+ * constraint's — because that is the one a `drop constraint` has to spell. The writers are asked
+ * whether they can write each statement and a refusal degrades the whole line to prose, the rule
+ * `changedForeignKey` states: every name on the live side is the catalog's.
+ */
+export function changedPrimaryKey(
+  schema: string,
+  table: string,
+  live: readonly string[],
+  held: string | undefined,
+  declared: readonly string[],
+): DriftDifference {
+  const statements = (): string => {
+    const names = [table, ...declared, ...(held === undefined ? [] : [held])];
+    const path = pathTo(schema);
+    if (path === null || !spellable(names)) return PRIMARY_KEY_BY_HAND;
+    try {
+      const parts: string[] = [];
+      if (held !== undefined) parts.push(dropPrimaryKey(table, held, false));
+      if (declared.length > 0) parts.push(addPrimaryKey(table, declared));
+      return repair(path, parts.join(' '));
+    } catch {
+      return PRIMARY_KEY_BY_HAND;
+    }
+  };
+  return {
+    kind: 'changed-primary-key',
+    table,
+    column: null,
+    cause:
+      `table "${table}" has ${keyText(live)}${held === undefined ? '' : ` as constraint "${held}"`}, ` +
+      'and migrations declare ' +
+      (declared.length === 0 ? 'none' : `(${declared.join(', ')})`),
+    fix: statements(),
   };
 }

package/src/drift.ts

@@ -9,6 +9,7 @@ import {
   changedColumn,
   changedForeignKey,
   changedIndex,
+  changedPrimaryKey,
   missingCheck,
   missingColumn,
   missingForeignKey,
@@ -23,6 +24,7 @@ import { foreignKeyTarget, onDeleteRule } from './foreign-key';
 import { indexMethodOf } from './index-method';
 import { findTable, introspect, type SchemaDescription, type TableDescription } from './introspect';
 import { type LedgerRow, type Migration, readLedger } from './migrate';
+import { sameColumns } from './primary-key';
 
 // Re-exported explicitly, never `export *`: `src/index.ts` publishes both from `'./drift'`, so the
 // split is invisible to `@ultimat3/db`'s public surface and no consumer moves with it.
@@ -145,7 +147,7 @@ function compareForeignKeys(live: TableDescription, expected: TableDescription):
       continue;
     }
     if (onDeleteRule(counterpart.onDelete) !== onDeleteRule(key.onDelete)) {
-      differences.push(changedForeignKey(live.name, key, counterpart));
+      differences.push(changedForeignKey(live.schema, live.name, key, counterpart));
     }
   }
   return differences;
@@ -175,26 +177,29 @@ function compareChecks(live: TableDescription, expected: TableDescription): Drif
   const present = new Set(held);
   return declared
     .filter((check) => !present.has(check.name))
-    .map((check) => missingCheck(live.name, check));
+    .map((check) => missingCheck(live.schema, live.name, check));
 }
 
 /**
- * A primary key column is `NOT NULL` in the catalog whether or not anything declared it — Postgres
- * adds the constraint with the key. Both sides are therefore read through the union of the two
- * primary keys, or a table whose snapshot spells its key column nullable reports a difference
- * against a database that is exactly right and cannot be anything else. The union, not one side:
- * a key present on only one of them is a difference the *key* comparison owns, and reporting it
- * again as a nullability change would be one fault with two findings.
+ * The two key lists, compared in ORDER. The comment that used to stand here said a key on one side
+ * only "is a difference the key comparison owns" — and no key comparison existed, so a table
+ * re-keyed by hand, or one whose key no migration ever produced, read `ok: true`.
  */
-function keyColumnsOf(live: TableDescription, expected: TableDescription): ReadonlySet<string> {
-  return new Set([...live.primaryKey, ...expected.primaryKey]);
+function comparePrimaryKey(live: TableDescription, expected: TableDescription): DriftDifference[] {
+  if (sameColumns(live.primaryKey, expected.primaryKey)) return [];
+  const held = live.indexes.find((index) => index.primary)?.name;
+  return [changedPrimaryKey(live.schema, live.name, live.primaryKey, held, expected.primaryKey)];
 }
 
 function compareTable(live: TableDescription, expected: TableDescription): DriftDifference[] {
   const differences: DriftDifference[] = [];
   const expectedColumns = new Map(expected.columns.map((column) => [column.name, column]));
   const liveColumns = new Map(live.columns.map((column) => [column.name, column]));
-  const keyColumns = keyColumnsOf(live, expected);
+  // A primary key column is `NOT NULL` in the catalog whether or not anything declared it —
+  // Postgres adds the constraint with the key — so a snapshot spelling its key column nullable is
+  // not drift. The DECLARED key only: a column the database alone keys stays NOT NULL after the
+  // stray constraint is dropped, which is a second fault and reported as one.
+  const keyColumns = new Set(expected.primaryKey);
   for (const column of live.columns) {
     if (expectedColumns.has(column.name)) continue;
     differences.push(unexpectedColumn(live.name, column.name));
@@ -210,9 +215,10 @@ function compareTable(live: TableDescription, expected: TableDescription): Drift
     // `retypeColumn` already owns that question where both sides are generated.
     if (keyColumns.has(column.name)) continue;
     if (column.nullable !== counterpart.nullable) {
-      differences.push(changedColumn(live.name, column.name, counterpart.nullable));
+      differences.push(changedColumn(live.schema, live.name, column.name, counterpart.nullable));
     }
   }
+  differences.push(...comparePrimaryKey(live, expected));
   differences.push(...compareIndexes(live, expected));
   differences.push(...compareChecks(live, expected));
   differences.push(...compareForeignKeys(live, expected));
@@ -224,7 +230,7 @@ export function diffSchema(live: SchemaDescription, expected: SchemaDescription)
   const differences: DriftDifference[] = [];
   for (const table of live.tables) {
     const counterpart = findTable(expected, table.name);
-    if (counterpart === undefined) differences.push(unexpectedTable(table.name));
+    if (counterpart === undefined) differences.push(unexpectedTable(table.schema, table.name));
     else differences.push(...compareTable(table, counterpart));
   }
   for (const table of expected.tables) {

package/src/errors.ts

@@ -38,6 +38,9 @@ export const DB_OWNED_ERROR_CODES = [
   'X_SQL_UNSAFE',
   'X_BRANCH_EXISTS',
   'X_SCHEMA_DUMP_DRIFT',
+  'X_DB_TRANSACTION_ABORTED',
+  'X_DB_COMMIT_UNKNOWN',
+  'X_DB_SIBLING_SCOPE_TIMEOUT',
 ] as const;
 
 /**
@@ -83,6 +86,9 @@ export const DB_ERROR_TITLES: Readonly<Record<DbOwnedErrorCode, string>> = {
   X_SQL_UNSAFE: 'SQL was built by string interpolation',
   X_BRANCH_EXISTS: 'that branch database already exists',
   X_SCHEMA_DUMP_DRIFT: 'the committed schema dump is not what the migrations produce',
+  X_DB_TRANSACTION_ABORTED: 'the server rolled the transaction back',
+  X_DB_COMMIT_UNKNOWN: 'the connection was lost while COMMIT was in flight',
+  X_DB_SIBLING_SCOPE_TIMEOUT: 'a nested transaction scope waited too long for its sibling',
 };
 
 // Registered unconditionally, in one call, so a second package claiming one of db's codes fails
@@ -416,10 +422,3 @@ export const isolationLevelInvalid = (received: unknown): DbError =>
     cause: `an isolation level must be one of 'read committed', 'repeatable read' or 'serializable'; got ${describeValue(received)}`,
     fix: "withTransaction(fn, { isolation: 'serializable' })   # or 'repeatable read', or 'read committed'",
   });
-
-export const dbNotImplemented = (feature: string, fix: string): DbError =>
-  new DbError({
-    code: 'X_NOT_IMPLEMENTED',
-    cause: `${feature} is not implemented by this driver`,
-    fix,
-  });

package/src/foreign-key.ts

@@ -130,37 +130,3 @@ export function unrestorableNote(table: string, constraint: string, gone: string
     `cannot be restored; ${identifier(gone).text} is gone`
   );
 }
-
-/**
- * The drop/add pair that moves a key's `on delete` rule — a rebuild, because Postgres has no
- * `alter constraint` for it — for a `fix:` line an author pastes into a new migration.
- *
- * It lives here, beside the two writers, because it is the one caller reading values neither of
- * them may assume: `held` is the **live catalog's** and `declared` is a `.snapshot.json`'s. Both
- * writers refuse rather than guess — `identifier()` on a name holding a quote, a space or a
- * backslash (all three legal inside a quoted Postgres name), and `addForeignKey` on an `on delete`
- * rule Postgres does not have. That is exactly right for DDL this package SENDS and wrong for a
- * `fix:` line: `diffSchema` is documented pure and total, so a pair it cannot write is a sentence,
- * never a throw — a drift check that raises in place of its report hands the caller an exception
- * where a verdict was asked for. The constraint is still named, because it is the only thing
- * identifying which one, quoted by `JSON.stringify`, which escapes rather than refuses; nothing
- * runs this string either way.
- */
-export function rebuildForeignKey(
-  table: string,
-  declared: ForeignKeyDescription,
-  held: ForeignKeyDescription,
-): string {
-  // The writers are ASKED whether they can write the pair — never a second copy of their rules
-  // beside them, which is the copy that drifts. A refusal is the answer, and nothing here reads
-  // the thrown value.
-  try {
-    return `${dropForeignKey(table, held.name)} ${addForeignKey(table, declared)}`;
-  } catch {
-    return (
-      `drop constraint ${JSON.stringify(held.name)} on table ${JSON.stringify(table)} and add ` +
-      'it back with the on delete rule the migrations declare — by hand: x db gen cannot ' +
-      'write this pair'
-    );
-  }
-}

package/src/generate.ts

@@ -23,6 +23,7 @@ import {
 } from './introspect';
 import { declaredIndexes } from './invariant-ddl';
 import { migrationIrreversible } from './migration-errors';
+import { addChangedKey, dropChangedKey } from './primary-key';
 import type { ReplicaIdentityInput } from './replica-identity';
 import { replicaIdentityFullAfter, replicaIdentityPlan } from './replica-identity';
 import type { MovedAside } from './retype-dependents';
@@ -324,6 +325,9 @@ export function generateMigration(options: GenerateOptions): GeneratedMigration
       created.add(entity.table);
       continue;
     }
+    // The key first and last, around every column statement of the table (`primary-key.ts`): the
+    // snapshot below records `entity.primaryKey`, and until this arm existed nothing produced it.
+    dropChangedKey(entity, live, current, plan, options.name);
     diffTable(entity, live, plan, retypedIn(retyped, entity.table));
     const kept = new Set(entity.columns.map((column) => column.column));
     for (const column of live.columns) {
@@ -343,6 +347,7 @@ export function generateMigration(options: GenerateOptions): GeneratedMigration
           ' -- data is not restored',
       );
     }
+    addChangedKey(entity, live, plan, options.name);
   }
 
   const order = dropOrder(current.tables.filter((table) => !wanted.has(table.name)));

package/src/index.ts

@@ -72,7 +72,6 @@ export {
   DB_ERROR_RETRY,
   DB_ERROR_TITLES,
   DbError,
-  dbNotImplemented,
   dbUnavailable,
   driverError,
   identifierUnsafe,
@@ -185,6 +184,7 @@ export { BREAKER_COOLDOWN_MS, BREAKER_FAILURES, replicatedClient } from './repli
 export { type DbNode, isPlainRead } from './replica-route';
 export type { ReplicaScope } from './replica-scope';
 export { markScopeWrote, replicaScope, withReplicaReads } from './replica-scope';
+export { SIBLING_SCOPE_WAIT_MS } from './sibling-turn';
 export { snapshotJson } from './snapshot-json';
 export { parseSnapshot } from './snapshot-parse';
 export type { SqlFragment } from './sql';
@@ -203,8 +203,10 @@ export { DB_SQLSTATE_CODES, isRetryableState, SQLSTATE, sqlState, sqlStateCode }
 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';
+export { currentTx, liveTxConnection, withTransaction } from './transaction';
+export { commitUnknown, siblingScopeTimeout, transactionAborted } from './transaction-errors';
+export type { DbTx, IsolationLevel, TransactionOptions } from './transaction-options';
+export { beginStatement } from './transaction-options';
 export type { GeneratableForm } from './ungeneratable';
 export { GENERATABLE_FORMS, ungeneratableStatements } from './ungeneratable';
 export type { UnrenderedDeclaration } from './unrendered';

package/src/introspect-catalog.ts

@@ -79,6 +79,12 @@ export async function introspectCatalog(
   const unrendered = await unrenderedRows(client, schema);
   const known = new Set(tables.map((table) => table.name));
   const materialized = new Set(views.filter((view) => view.kind === 'm').map((view) => view.name));
+  // A trigger loads only onto a relation the dump creates: a plain table, or a view (`instead
+  // of`). One on a partitioned table or a partition was filed under `09_triggers/` for a table no
+  // file creates, and the load refused the whole dump with `X_SCHEMA_DUMP_DRIFT`.
+  const viewNames = new Set(views.map((view) => view.name));
+  const loadable = (trigger: { readonly table_name: string }): boolean =>
+    known.has(trigger.table_name) || viewNames.has(trigger.table_name);
 
   return {
     schema,
@@ -129,6 +135,7 @@ export async function introspectCatalog(
         ),
       ),
     triggers: triggers
+      .filter(loadable)
       .map((row) => ({
         table: row.table_name,
         name: row.name,
@@ -141,7 +148,17 @@ export async function introspectCatalog(
           (trigger) => trigger.name,
         ),
       ),
-    unrendered: unrendered
+    unrendered: [
+      ...unrendered,
+      // Named rather than dropped, the rule `CatalogUnrendered` states.
+      ...triggers
+        .filter((trigger) => !loadable(trigger))
+        .map((trigger) => ({
+          kind: 'trigger',
+          name: trigger.name,
+          table_name: trigger.table_name,
+        })),
+    ]
       .map((row) => ({ kind: row.kind, name: row.name, table: row.table_name }))
       .sort(
         by(