@ultimat3/db 22.15.0 → 24.0.0

package/src/client.ts

@@ -4,7 +4,7 @@
 // `Bun.SQL` slice in `bun-sql.ts` and the observed statement funnel in `statement-funnel.ts`, so
 // importing this module never opens a socket.
 
-import { type Role, resolveRole } from '@ultimat3/core';
+import { logger, type Role, renderThrowable, resolveRole } from '@ultimat3/core';
 import {
   type BunSqlDriver,
   type BunSqlReserved,
@@ -17,6 +17,13 @@ import { connectionUrl } from './connection-url';
 // module evaluation, and both sides are `function` declarations, so hoisting covers the TDZ.
 import { defaultClient } from './default-client';
 import { DbError, drainTimeout, driverError } from './errors';
+import {
+  assertListenChannel,
+  type DbSubscription,
+  type ListeningClient,
+  listenUnsupported,
+} from './listen';
+import { type PoolDemand, trackPool } from './pool-gauge';
 import { assertPoolProfile, type PoolProfile, poolProfileFor } from './pool-profile';
 import { reserveWithin } from './pool-reserve';
 import { type SqlFragment, sql } from './sql';
@@ -55,7 +62,7 @@ export interface PostgresClientOptions {
   readonly applicationName?: string | undefined;
 }
 
-export interface PostgresClient extends ReservableClient {
+export interface PostgresClient extends ReservableClient, ListeningClient {
   readonly profile: PoolProfile;
   ping(): Promise<void>;
   close(): Promise<void>;
@@ -68,18 +75,28 @@ export function createPostgresClient(options: PostgresClientOptions = {}): Postg
     ...poolProfileFor(role),
     ...(options.profile ?? {}),
   });
-  let driver: BunSqlDriver | undefined;
+  // The driver and what `db_pool_in_use` / `db_pool_waiting` are derived from (`pool-gauge.ts`),
+  // as ONE value: a pool still draining after `close()` settles its own work against its own
+  // counter, never against the pool that replaced it. Built only once the driver exists, so a
+  // connection string that cannot be built registers no pool in `db_pool_max`.
+  let driver: { readonly pool: BunSqlDriver; readonly demand: PoolDemand } | undefined;
 
-  function connect(): BunSqlDriver {
+  function connect(): { readonly pool: BunSqlDriver; readonly demand: PoolDemand } {
     if (driver !== undefined) return driver;
     const url = connectionUrl(options, profile);
     const Factory = bunSqlFactory();
-    driver = new Factory(url, bunSqlPoolOptions(profile));
+    driver = { pool: new Factory(url, bunSqlPoolOptions(profile)), demand: trackPool(profile.max) };
     return driver;
   }
 
   async function run(fragment: SqlFragment): Promise<unknown> {
-    return runOn(connect(), fragment);
+    const { pool, demand } = connect();
+    demand.enter();
+    try {
+      return await runOn(pool, fragment);
+    } finally {
+      demand.leave();
+    }
   }
 
   const client: PostgresClient = {
@@ -99,11 +116,14 @@ export function createPostgresClient(options: PostgresClientOptions = {}): Postg
       // (`ERR_POSTGRES_UNSAFE_TRANSACTION`), and a BEGIN that landed on a different connection
       // than the statement after it would not be a transaction at all — which is exactly what
       // `withTransaction` and `readOnlyQuery` depend on being true.
-      const pool = connect();
+      const { pool, demand } = connect();
       let reserved: BunSqlReserved;
+      // Counted from the ASK: a pin queued behind a full pool is exactly what `waiting` reports.
+      demand.enter();
       try {
         reserved = await reserveWithin(pool, profile);
       } catch (error) {
+        demand.leave();
         // Acquiring the pin is the one step that runs outside `runOn`, so an exhausted or
         // unreachable pool would escape as an untyped driver error — and `readOnlyQuery` reaches
         // this line before its first statement, which is how MCP ends up returning something
@@ -126,6 +146,7 @@ export function createPostgresClient(options: PostgresClientOptions = {}): Postg
       const release = (): void => {
         if (!held) return;
         held = false;
+        demand.leave();
         // Total by construction — `releaseReserved` owns the reason (`bun-sql.ts`).
         releaseReserved(reserved);
       };
@@ -137,6 +158,30 @@ export function createPostgresClient(options: PostgresClientOptions = {}): Postg
         [Symbol.dispose]: release,
       };
     },
+    async listen(channel, onNotify, onListening): Promise<DbSubscription> {
+      assertListenChannel(channel);
+      const { pool } = connect();
+      if (pool.listen === undefined) throw listenUnsupported('this Bun.SQL');
+      let held: { unlisten(): Promise<void> };
+      try {
+        // The driver's own session, never a pin out of the pool: a reserved connection holds the
+        // LISTEN and surfaces no notification, and it would cost the pool a slot for good.
+        held = await pool.listen(channel, onNotify, onListening);
+      } catch (error) {
+        throw driverError(`LISTEN ${channel}`, error);
+      }
+      let ended: Promise<void> | undefined;
+      return {
+        unlisten: () => {
+          // Best-effort, the rule `releaseReserved` states: the session this would end may be
+          // gone with the pool already, and that is the outcome asked for.
+          ended ??= held.unlisten().catch((error: unknown) => {
+            logger.debug('db.unlisten_failed', { error: renderThrowable(error) });
+          });
+          return ended;
+        },
+      };
+    },
     async ping(): Promise<void> {
       await client.query(sql`select 1`);
     },
@@ -146,9 +191,12 @@ export function createPostgresClient(options: PostgresClientOptions = {}): Postg
       // after it would fail for a reason no caller can see. Clearing first also means a
       // `connect()` racing the await opens a fresh pool instead of joining the one draining. The
       // rejection still reaches the caller — a shutdown that could not drain wants to know.
-      const pool = driver;
+      const closing = driver;
       driver = undefined;
-      if (pool === undefined) return;
+      if (closing === undefined) return;
+      // Only THIS pool's counter leaves the totals; its in-flight work settles against it.
+      closing.demand.close();
+      const { pool } = closing;
       // BOUNDED, `As of 2026-08-27`, and through the driver's OWN option rather than a race here.
       // This was a bare `await pool.close()`, and `Bun.SQL`'s `end()` waits on an outstanding
       // reserved connection without ever giving up — measured three runs per case on Bun 1.3.14

package/src/commit-tag.ts

@@ -0,0 +1,21 @@
+// Single responsibility: the server's answer to `COMMIT`, read. Postgres answers a COMMIT on an
+// aborted transaction with the command tag `ROLLBACK` and NO error, so a driver that reports only
+// rejections calls a rolled-back unit of work committed. Both funnels (`statement-funnel.ts`,
+// `pglite.ts`) ask here, so every COMMIT in the process is covered and not only `withTransaction`'s.
+
+import { stringField } from '@ultimat3/core';
+import { transactionAborted } from './transaction-errors';
+
+/** `COMMIT` and its alias `END`, as the first word. Only consulted once the tag already disagrees. */
+const COMMIT_STATEMENT = /^\s*(?:commit|end)\b/i;
+
+/**
+ * Throws `X_DB_TRANSACTION_ABORTED` when `text` asked for a commit and the tag says `ROLLBACK`.
+ * The tag is read first: one property read per statement on the path every statement takes, and
+ * the regular expression runs only for a statement that really was answered `ROLLBACK`. Both
+ * drivers carry the tag on `command` — measured on Bun.SQL against Postgres 17 and on PGlite.
+ */
+export function refuseRolledBackCommit(text: string, result: unknown): void {
+  if (stringField(result, 'command') !== 'ROLLBACK') return;
+  if (COMMIT_STATEMENT.test(text)) throw transactionAborted();
+}

package/src/dependent-view.ts

@@ -139,6 +139,7 @@ async function dependentViews(
       join pg_attribute a on a.attrelid = c.oid and a.attnum = d.refobjsubid
      where v.relkind in ('v', 'm') and v.oid <> c.oid
        and c.relname in (${tables}) and a.attname in (${columns})
+       and pg_table_is_visible(c.oid)
      order by v.relname
   `);
 }
@@ -155,7 +156,8 @@ async function dependentViews(
 const shellArg = (statement: string): string => `'${statement.replaceAll("'", `'\\''`)}'`;
 
 /** The invocation `migrationConflict` already writes, with the statement as its own argv word. */
-const psql = (statement: string): string => `psql "$DATABASE_URL" -c ${shellArg(statement)}`;
+export const psqlCommand = (statement: string): string =>
+  `psql "$DATABASE_URL" -c ${shellArg(statement)}`;
 
 /**
  * The two statements that unblock the deploy, as one line an operator pastes.
@@ -166,7 +168,7 @@ const psql = (statement: string): string => `psql "$DATABASE_URL" -c ${shellArg(
  * a shell read `drop` as a program that does not exist. Neither reader could run it (axiom 4).
  *
  * `identifier()` REFUSES a name holding a quote, a space or a backslash — all three legal inside a
- * quoted Postgres name — and a `fix:` may not throw: the rule `rebuildForeignKey` already states,
+ * quoted Postgres name — and a `fix:` may not throw: the rule `changedForeignKey` (`drift-findings.ts`) states,
  * with the same shape. A refusal that raised `X_SQL_UNSAFE` in place of the finding would hand the
  * operator an exception where a verdict was asked for, over a view name that is perfectly legal.
  * The fallback still leads with a command that runs — a psql session — because quoting that name
@@ -192,8 +194,8 @@ function restoreView(view: string, definition: string, relkind: string): string
   try {
     const name = identifier(view).text;
     return (
-      `${psql(`drop ${kind} ${name}`)}   # then x db migrate, then: ` +
-      `${psql(`create ${kind} ${name} as ${body}`)}${note}`
+      `${psqlCommand(`drop ${kind} ${name}`)}   # then x db migrate, then: ` +
+      `${psqlCommand(`create ${kind} ${name} as ${body}`)}${note}`
     );
   } catch {
     return (

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,9 +19,13 @@ export type DriftKind =
   | 'unknown-schema'
   | 'missing-index'
   | 'changed-index'
+  | 'changed-primary-key'
   | 'missing-check'
   | 'missing-foreign-key'
-  | 'changed-foreign-key';
+  | 'changed-foreign-key'
+  // Constructed in `object-drift.ts`: a trigger, function, view, type or sequence in the live
+  // database that replaying the migrations does not create.
+  | 'unexpected-object';
 
 export interface DriftDifference {
   readonly kind: DriftKind;
@@ -42,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
@@ -90,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 {
@@ -106,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,
+          ),
   };
 }
 
@@ -131,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`,
   };
 }
 
@@ -173,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.
@@ -193,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',
   };
 }
 
@@ -229,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 {
@@ -242,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});`,
+          ),
   };
 }
 
@@ -279,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(),
   };
 }