@ultimat3/db 29.4.0 → 30.0.0

package/src/db-diagnostics.ts

@@ -0,0 +1,178 @@
+// Single responsibility: `dbDiagnostics()` — what the database is doing right now (blockers,
+// activity, slow statements, unused and invalid indexes, unvalidated constraints, dead tuples), as
+// facts and never a verdict. `db-health.ts` stays the readiness probe `/readyz` reads.
+
+import { finiteCount, isUltimateError, renderThrowable, type Scheduler } from '@ultimat3/core';
+import type { DbClient } from './client';
+import { commandDeadline, EXPIRED, within } from './db-diagnostics-deadline';
+import { redactQueryText } from './db-diagnostics-redact';
+import {
+  type ActivityRow,
+  activityRow,
+  type BlockerRow,
+  blockerRow,
+  type DeadTupleRow,
+  deadTupleRow,
+  type InvalidIndexRow,
+  invalidIndexRow,
+  type NotValidConstraintRow,
+  notValidConstraintRow,
+  type SlowQueryRow,
+  slowQueryRow,
+  type UnusedIndexRow,
+  unusedIndexRow,
+} from './db-diagnostics-rows';
+import {
+  ACTIVITY_SQL,
+  BLOCKERS_SQL,
+  DEAD_TUPLES_SQL,
+  INVALID_INDEXES_SQL,
+  NOT_VALID_CONSTRAINTS_SQL,
+  SLOW_QUERIES_SQL,
+  UNUSED_INDEXES_SQL,
+} from './db-diagnostics-sql';
+import { dbUnavailable } from './errors';
+import { unrefSchedule } from './pool-timer';
+import { readOnlyQuery } from './readonly-query';
+
+/** Per statement. A catalog read that takes longer is itself the finding, reported as its section. */
+export const DIAGNOSTICS_TIMEOUT_MS = 2_000;
+/** Rows per section, fetched through a cursor so the server stops there. */
+export const DIAGNOSTICS_LIMIT = 20;
+/** The client's own wait per statement: the server's bound plus a second for the answer to land. */
+export const DIAGNOSTICS_SECTION_DEADLINE_MS = DIAGNOSTICS_TIMEOUT_MS + 1_000;
+/** The whole command. Past it, the sections not yet asked are reported unsent. */
+export const DIAGNOSTICS_DEADLINE_MS = 15_000;
+
+export interface DbDiagnosticsOptions {
+  /** Override the ambient pool. */
+  readonly client?: DbClient | undefined;
+  /** Rows per section; a whole number ≥ 1. Default `DIAGNOSTICS_LIMIT`. */
+  readonly limit?: number | undefined;
+  /** Arms both client-side deadlines. A seam for tests; default an unref'd `setTimeout`. */
+  readonly schedule?: Scheduler | undefined;
+}
+
+/** A section answered, or why it could not be and what would make it answer. Never a throw. */
+export type DiagnosticSection<Row> =
+  | { readonly available: true; readonly rows: readonly Row[] }
+  | {
+      readonly available: false;
+      readonly code: string;
+      readonly reason: string;
+      readonly fix: string;
+    };
+
+export interface DbDiagnostics {
+  readonly blockers: DiagnosticSection<BlockerRow>;
+  readonly activity: DiagnosticSection<ActivityRow>;
+  readonly slowQueries: DiagnosticSection<SlowQueryRow>;
+  readonly unusedIndexes: DiagnosticSection<UnusedIndexRow>;
+  readonly invalidIndexes: DiagnosticSection<InvalidIndexRow>;
+  readonly notValidConstraints: DiagnosticSection<NotValidConstraintRow>;
+  readonly deadTuples: DiagnosticSection<DeadTupleRow>;
+}
+
+/** An operator's act, in the database: this framework never creates an extension for the app. */
+export const SLOW_QUERIES_FIX =
+  `psql "$DATABASE_URL" -c 'create extension if not exists pg_stat_statements'` +
+  "   # after shared_preload_libraries = 'pg_stat_statements' in postgresql.conf and a server restart";
+
+/** A section the client stopped waiting for, or never sent: the server's own timeout code. */
+const TIMED_OUT = 'X_DB_STATEMENT_TIMEOUT';
+
+/** What a section without an `UltimateError` of its own hands out: the same read, by hand. */
+const GENERIC_FIX =
+  'x db diagnostics --json   # re-run once the load that timed this read out passes';
+
+/** `scheme://user:password@host` → `scheme://***@host`: a reason is printed, a credential never. */
+const scrubCredentials = (text: string): string =>
+  text.replace(/([a-z][a-z0-9+.-]*:\/\/)[^\s/@'"]*@/gi, '$1***@');
+
+/**
+ * Every section is one statement through `readOnlyQuery` — its own `BEGIN READ ONLY`, a 2 s
+ * `statement_timeout`, a cursor capped at `limit` — run one after another, so a diagnostic holds
+ * one connection and never seven. A section that fails is reported in place: one timeout does not
+ * lose the other six. The single throw is a probe that cannot open a connection at all.
+ */
+export async function dbDiagnostics(options: DbDiagnosticsOptions = {}): Promise<DbDiagnostics> {
+  const limit = finiteCount('dbDiagnostics', 'limit', options.limit ?? DIAGNOSTICS_LIMIT, 1);
+  const read = { client: options.client, timeoutMs: DIAGNOSTICS_TIMEOUT_MS } as const;
+  const schedule = options.schedule ?? unrefSchedule;
+  const sectionMs = DIAGNOSTICS_SECTION_DEADLINE_MS;
+  try {
+    const probe = await within(readOnlyQuery('select 1', read), sectionMs, schedule);
+    if (probe === EXPIRED) {
+      throw dbUnavailable(`x db diagnostics had no answer to select 1 within ${sectionMs}ms`);
+    }
+  } catch (error) {
+    throw isUltimateError(error)
+      ? error
+      : dbUnavailable('x db diagnostics could not open a connection', error);
+  }
+  const deadline = commandDeadline(DIAGNOSTICS_DEADLINE_MS, schedule);
+  const section = async <Row>(
+    statement: string,
+    toRow: (raw: Readonly<Record<string, unknown>>) => Row,
+    fixFor?: (code: string, reason: string) => string | undefined,
+  ): Promise<DiagnosticSection<Row>> => {
+    if (deadline.passed()) {
+      const reason = `not sent: x db diagnostics passed its ${DIAGNOSTICS_DEADLINE_MS}ms deadline first`;
+      return { available: false, code: TIMED_OUT, reason, fix: GENERIC_FIX };
+    }
+    try {
+      const answer = await within(
+        readOnlyQuery<Readonly<Record<string, unknown>>>(statement, { ...read, maxRows: limit }),
+        sectionMs,
+        schedule,
+      );
+      if (answer === EXPIRED) {
+        // The embedded database cannot interrupt the statement, so it may still be running.
+        const reason = `no answer within ${sectionMs}ms; the client stopped waiting`;
+        return { available: false, code: TIMED_OUT, reason, fix: GENERIC_FIX };
+      }
+      return { available: true, rows: answer.rows.map(toRow) };
+    } catch (error) {
+      const code = isUltimateError(error) ? error.code : 'X_DB_STATEMENT_FAILED';
+      const reason = scrubCredentials(
+        isUltimateError(error) ? error.cause : renderThrowable(error),
+      );
+      const own = isUltimateError(error) ? error.fix : undefined;
+      const fix = fixFor?.(code, reason) ?? own ?? GENERIC_FIX;
+      return { available: false, code, reason, fix: scrubCredentials(fix) };
+    }
+  };
+  try {
+    return await readSections(section);
+  } finally {
+    deadline.release();
+  }
+}
+
+type Section = <Row>(
+  statement: string,
+  toRow: (raw: Readonly<Record<string, unknown>>) => Row,
+  fixFor?: (code: string, reason: string) => string | undefined,
+) => Promise<DiagnosticSection<Row>>;
+
+/** The seven, in order, each through `section`. */
+async function readSections(section: Section): Promise<DbDiagnostics> {
+  return {
+    blockers: await section(BLOCKERS_SQL, (raw) => blockerRow(raw, redactQueryText)),
+    activity: await section(ACTIVITY_SQL, (raw) => activityRow(raw, redactQueryText)),
+    // `42P01` (not installed) and `55000` (installed, not preloaded) both mean the extension is
+    // not answering — its own fix, never `X_DB_SCHEMA_STALE`'s `x db gen`.
+    slowQueries: await section(
+      SLOW_QUERIES_SQL,
+      (raw) => slowQueryRow(raw, redactQueryText),
+      (code, reason) =>
+        code === 'X_DB_SCHEMA_STALE' || reason.includes('pg_stat_statements')
+          ? SLOW_QUERIES_FIX
+          : undefined,
+    ),
+    unusedIndexes: await section(UNUSED_INDEXES_SQL, unusedIndexRow),
+    invalidIndexes: await section(INVALID_INDEXES_SQL, invalidIndexRow),
+    notValidConstraints: await section(NOT_VALID_CONSTRAINTS_SQL, notValidConstraintRow),
+    deadTuples: await section(DEAD_TUPLES_SQL, deadTupleRow),
+  };
+}

package/src/destructive.ts

@@ -41,6 +41,20 @@ export interface DestructiveStatement {
   readonly statement: string;
 }
 
+/**
+ * Inside an `alter table`, a bare `drop <name>` is a column: every sub-clause that drops something
+ * the database can rebuild names itself, and all of them are listed here. One list, two readers:
+ * this file's regex and `rolling.ts`'s token walk.
+ */
+export const REBUILDABLE_DROP_CLAUSES: readonly string[] = [
+  'constraint',
+  'default',
+  'not',
+  'identity',
+  'expression',
+  'generated',
+];
+
 /**
  * The closed list. Four kinds, because a rail that tried to enumerate every Postgres foot-gun
  * would be a second SQL parser competing with the server's own — and every one of these is a
@@ -54,11 +68,11 @@ const RULES: readonly (readonly [DestructiveKind, RegExp])[] = [
   // Statement-leading only: `before truncate` in a trigger and `grant/revoke truncate` name the
   // operation to guard or permit it, and the rail read them as the operation itself (#522).
   ['truncate', /^\s*truncate\b/],
-  // Inside an `alter table`, a bare `drop <name>` is a column: every sub-clause that drops
-  // something the database can rebuild names itself, and all of them are listed here.
   [
     'drop-column',
-    /\balter\s+table\b[\s\S]*?\bdrop\s+(?!constraint\b|default\b|not\b|identity\b|expression\b|generated\b)/,
+    new RegExp(
+      `\\balter\\s+table\\b[\\s\\S]*?\\bdrop\\s+(?!${REBUILDABLE_DROP_CLAUSES.map((clause) => `${clause}\\b`).join('|')})`,
+    ),
   ],
   // Not "narrowing". Whether the new type is narrower is knowable only against the old one, and a
   // rewrite that fails on one row fails the whole migration whichever direction it went.

package/src/diagnostics-entry.ts

@@ -0,0 +1,15 @@
+// `@ultimat3/db/diagnostics`: `dbDiagnostics()` and its row types. Its own entry because one caller
+// runs it — `x db diagnostics` — while `@ultimat3/db` is imported by every role of every app: on the
+// barrel these five modules were evaluated by every web, worker and migrate pod to serve nothing.
+
+export type { DbDiagnostics, DbDiagnosticsOptions, DiagnosticSection } from './db-diagnostics';
+export { DIAGNOSTICS_LIMIT, DIAGNOSTICS_TIMEOUT_MS, dbDiagnostics } from './db-diagnostics';
+export type {
+  ActivityRow,
+  BlockerRow,
+  DeadTupleRow,
+  InvalidIndexRow,
+  NotValidConstraintRow,
+  SlowQueryRow,
+  UnusedIndexRow,
+} from './db-diagnostics-rows';

package/src/drift-errors.ts

@@ -9,6 +9,13 @@
 import { DbError } from './errors';
 import { shellInertIdentifier } from './sql';
 
+/**
+ * What a `x db gen` fix owes after its `#`. It diffs entities against the newest snapshot, so a column
+ * only a migration holds is an empty diff: exit 0, the finding still there. Both ways out are named.
+ */
+export const undeclaredColumnNext = (column: string): string =>
+  `declare ${column} on its entity first, or this writes nothing; no entity should hold it: restore the edited migration, then x db reset`;
+
 /**
  * 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
@@ -28,9 +35,7 @@ export const dbDrift = (tableName: string, columnName: string): DbError =>
     cause: `table "${tableName}" has column "${columnName}" not present in any migration`,
     fix:
       shellInertIdentifier(columnName) === null
-        ? 'x db gen "add the column named in this error"   # its name carries a backtick, a ' +
-          'dollar sign, a quote, a backslash or whitespace, so it is in the cause and not in ' +
-          'this command'
-        : `x db gen "add ${columnName}"`,
+        ? `x db gen "add the column named in this error"   # its name carries shell syntax, so it is in the cause and not in this command; ${undeclaredColumnNext('it')}`
+        : `x db gen "add ${columnName}"   # ${undeclaredColumnNext(columnName)}`,
     meta: { table: tableName, column: columnName },
   });

package/src/drift-findings.ts

@@ -1,10 +1,11 @@
 // 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
+// constructor per `DriftKind` (the missing-or-rebuilt ones in `drift-missing.ts`), 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 { psqlCommand } from './dependent-view';
-import { addForeignKey, dropForeignKey, onDeleteRule } from './foreign-key';
+import { undeclaredColumnNext } from './drift-errors';
+import { addForeignKey, dropForeignKey, onDeleteRule, validateConstraint } from './foreign-key';
 import type { CheckDescription, ForeignKeyDescription } from './introspect';
 import type { Migration } from './migrate';
 import { addPrimaryKey, dropPrimaryKey } from './primary-key';
@@ -23,8 +24,17 @@ export type DriftKind =
   | 'missing-check'
   | 'missing-foreign-key'
   | 'changed-foreign-key'
+  // A declared constraint the catalog holds `NOT VALID`: the deferred step's validate never finished.
+  | 'not-valid-constraint'
   // Constructed in `drift-append-only.ts`: an `appendOnly` table whose refusing trigger is gone.
   | 'missing-append-only-trigger'
+  // Constructed in `drift-triggers.ts`: a history, guard or counter trigger gone, or a retain table
+  // the catalog holds partitioned.
+  | 'missing-lifecycle-trigger'
+  | 'retain-partitioned'
+  // Constructed in `drift-row-security.ts`: a tenant policy missing, or present unrecorded.
+  | 'missing-row-security'
+  | 'unexpected-row-security'
   // 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';
@@ -42,10 +52,10 @@ export interface DriftReport {
   readonly differences: readonly DriftDifference[];
 }
 
-const RE_CHECK = 'then x db migrate, which re-checks';
+export 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}`;
+export 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';
@@ -99,7 +109,7 @@ const qualified = (schema: string, table: string): string | null => {
 };
 
 /** Every name inert in a shell AND writable as an identifier — the one screen, asked of each. */
-const spellable = (names: readonly string[]): boolean =>
+export const spellable = (names: readonly string[]): boolean =>
   names.every((name) => shellInertIdentifier(name) !== null);
 
 /**
@@ -120,20 +130,8 @@ export function unexpectedColumn(table: string, column: string): DriftDifference
     cause: `table "${table}" has column "${column}" not present in any migration`,
     fix:
       shellInertIdentifier(column) === null
-        ? 'x db gen "add the undeclared column"   # the live column name carries a backtick, a ' +
-          'dollar sign, a quote, a backslash or whitespace, so it is in the cause and not in ' +
-          'this command'
-        : `x db gen "add ${column}"`,
-  };
-}
-
-export function missingColumn(table: string, column: string): DriftDifference {
-  return {
-    kind: 'missing-column',
-    table,
-    column,
-    cause: `table "${table}" is missing column "${column}" that migrations declare`,
-    fix: 'x db migrate',
+        ? `x db gen "add the undeclared column"   # the live column name carries shell syntax, so it is in the cause and not in this command; ${undeclaredColumnNext('it')}`
+        : `x db gen "add ${column}"   # ${undeclaredColumnNext(column)}`,
   };
 }
 
@@ -222,16 +220,6 @@ export function unexpectedTable(schema: string, table: string): DriftDifference
   };
 }
 
-export function missingTable(table: string): DriftDifference {
-  return {
-    kind: 'missing-table',
-    table,
-    column: null,
-    cause: `table "${table}" is declared by migrations but does not exist`,
-    fix: 'x db migrate',
-  };
-}
-
 /**
  * Not a difference between two schemas but the absence of one to compare against — reported
  * through the same channel so it reaches an operator, since a check that quietly answered "clean"
@@ -272,26 +260,6 @@ export function unknownSchema(migrations: readonly Migration[]): DriftDifference
   };
 }
 
-export function missingIndex(table: string, index: string): DriftDifference {
-  return {
-    kind: 'missing-index',
-    table,
-    column: null,
-    cause: `table "${table}" is missing index "${index}" that migrations declare`,
-    fix: 'x db migrate',
-  };
-}
-
-export function changedIndex(table: string, index: string, detail: string): DriftDifference {
-  return {
-    kind: 'changed-index',
-    table,
-    column: null,
-    cause: `index "${index}" on "${table}" ${detail}, not what migrations declare`,
-    fix: 'x db migrate',
-  };
-}
-
 /**
  * A CHECK a migration declares and the catalog does not hold.
  *
@@ -334,18 +302,6 @@ export function missingCheck(
   };
 }
 
-export function missingForeignKey(table: string, key: ForeignKeyDescription): DriftDifference {
-  return {
-    kind: 'missing-foreign-key',
-    table,
-    column: null,
-    cause:
-      `table "${table}" has no foreign key on (${key.columns.join(', ')}) to ` +
-      `"${key.referencedTable}" (${key.referencedColumns.join(', ')}) that migrations declare`,
-    fix: 'x db migrate',
-  };
-}
-
 /**
  * The key points where it was declared to point and one side's `on delete` rule is not the other's
  * — reported apart from `missing-foreign-key` because it is a different repair: the constraint is
@@ -405,6 +361,35 @@ export function changedForeignKey(
   };
 }
 
+/**
+ * The constraint is there and holds every new write; rows that predate it are unchecked. Left by a
+ * deferred step that stopped between its add and its validate, or by hand. The fix is the validate
+ * statement (`repair`), because a ledger that recorded the step will apply nothing on a re-run; a
+ * step still pending is re-run by `x db migrate`, whose validate is the same statement.
+ */
+export function notValidConstraint(
+  schema: string,
+  table: string,
+  constraint: string,
+): DriftDifference {
+  const path = pathTo(schema);
+  const steps = 'alter table … validate constraint … on the constraint this difference names';
+  return {
+    kind: 'not-valid-constraint',
+    table,
+    column: null,
+    cause: `constraint "${constraint}" on "${table}" is NOT VALID: rows older than it were never checked`,
+    fix:
+      path === null || !spellable([table, constraint])
+        ? byHand(steps)
+        : repair(
+            path,
+            validateConstraint(table, constraint),
+            'a row it finds is X_DB_FOREIGN_KEY_VIOLATION or a CHECK failure: repair that row, then run it again',
+          ),
+  };
+}
+
 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`,

package/src/drift-missing.ts

@@ -0,0 +1,203 @@
+// Single responsibility: the findings for something a migration declares that the catalog lacks
+// or holds rebuilt — a table, a column, an index, a foreign key — each with the statement that puts
+// it back, built from the snapshot. Split from `drift-findings.ts`, whose helpers these share.
+
+import {
+  byHand,
+  type DriftDifference,
+  NULLS_FIRST,
+  pathTo,
+  RE_CHECK,
+  repair,
+  spellable,
+} from './drift-findings';
+import { addForeignKey } from './foreign-key';
+import { asDeclared, createIndex, mayBeConstraintBacked } from './index-ddl';
+import type { ColumnDescription, ForeignKeyDescription, IndexDescription } from './introspect';
+import { identifier } from './sql';
+
+/**
+ * Why none of these says `x db migrate`: `checkDrift` compares the catalog with the migrations the
+ * LEDGER holds, so the migration that declares the missing thing has already run and re-running the
+ * migrator applies nothing — the same finding comes back. The fix is the statement, against this
+ * database (`repair`), the rule `missingCheck` and `changedPrimaryKey` already follow.
+ */
+
+/**
+ * A snapshot column as a column definition. `dataType`, `default` and `generated` are the DECLARED
+ * side's own text, out of the author's migration — the trust `missingCheck` gives its predicate —
+ * and `psqlCommand` closes the shell layer around all of it. `notNull` is the caller's: an `add
+ * column … not null` with no value to fill existing rows with is refused on a table holding any.
+ */
+const columnClause = (column: ColumnDescription, notNull: boolean): string => {
+  const value =
+    column.generated !== undefined
+      ? ` generated always as (${column.generated}) stored`
+      : column.default === null
+        ? ''
+        : ` default ${column.default}`;
+  return `${identifier(column.name).text} ${column.dataType}${value}${notNull ? ' not null' : ''}`;
+};
+
+/** Every row an `add column` lands on gets a value, so `not null` can ride on the same statement. */
+const filled = (column: ColumnDescription): boolean =>
+  column.default !== null || column.generated !== undefined;
+
+const LATER_NOT_NULL = `then x db migrate, which re-checks and names the set not null — ${NULLS_FIRST}`;
+
+/** The statement, or `byHand` when a name in it is refused or a writer refuses the declaration. */
+const statementOr = (
+  schema: string,
+  names: readonly string[],
+  steps: string,
+  write: () => string,
+  note = RE_CHECK,
+): string => {
+  const path = pathTo(schema);
+  if (path === null || !spellable(names)) return byHand(steps);
+  try {
+    return repair(path, write(), note);
+  } catch {
+    return byHand(steps, 'migrations declare it in a form no statement here can write');
+  }
+};
+
+/**
+ * Added NULLABLE when nothing fills the rows already there — the strict form fails on a populated
+ * table — and the re-check then reports `changed-column`, whose fix is the `set not null`.
+ */
+export function missingColumn(
+  schema: string,
+  table: string,
+  column: ColumnDescription,
+): DriftDifference {
+  const strict = !column.nullable && filled(column);
+  return {
+    kind: 'missing-column',
+    table,
+    column: column.name,
+    cause: `table "${table}" is missing column "${column.name}" that migrations declare`,
+    fix: statementOr(
+      schema,
+      [table, column.name],
+      'add the column this difference names back, as the migration that declares it does',
+      () => `alter table ${identifier(table).text} add column ${columnClause(column, strict)};`,
+      strict || column.nullable ? RE_CHECK : LATER_NOT_NULL,
+    ),
+  };
+}
+
+/**
+ * The table and its primary key only. An index, a foreign key, a check or a trigger has a finding
+ * of its own with its own repair, which the re-check reports next — one statement per fact, so a
+ * key to a table that is also missing is never part of the statement that would fail on it.
+ */
+export function missingTable(
+  schema: string,
+  table: string,
+  columns: readonly ColumnDescription[],
+  primaryKey: readonly string[],
+): DriftDifference {
+  const create = (): string => {
+    const clauses = [...columns]
+      .sort((a, b) => a.position - b.position)
+      .map((column) => columnClause(column, !column.nullable));
+    if (primaryKey.length > 0) {
+      clauses.push(`primary key (${primaryKey.map((name) => identifier(name).text).join(', ')})`);
+    }
+    return `create table ${identifier(table).text} (${clauses.join(', ')});`;
+  };
+  return {
+    kind: 'missing-table',
+    table,
+    column: null,
+    cause: `table "${table}" is declared by migrations but does not exist`,
+    fix: statementOr(
+      schema,
+      [table, ...columns.map((column) => column.name), ...primaryKey],
+      'create the table this difference names, as the migration that declares it does',
+      create,
+      `${RE_CHECK} and names its indexes, keys, checks and triggers next`,
+    ),
+  };
+}
+
+const indexNames = (table: string, index: IndexDescription): readonly string[] => [
+  table,
+  index.name,
+  ...index.columns,
+];
+
+export function missingIndex(
+  schema: string,
+  table: string,
+  index: IndexDescription,
+): DriftDifference {
+  return {
+    kind: 'missing-index',
+    table,
+    column: null,
+    cause: `table "${table}" is missing index "${index.name}" that migrations declare`,
+    fix: statementOr(
+      schema,
+      indexNames(table, index),
+      'create the index this difference names, as the migration that declares it does',
+      () => createIndex(table, asDeclared(index)),
+    ),
+  };
+}
+
+/**
+ * Postgres has no `alter index` for any part drift compares, so the repair is a drop and the
+ * declared build, in one transaction. A live index a UNIQUE constraint may own refuses `drop index`
+ * (2BP01), so its constraint goes first — `if exists`, because it may be a plain index after all.
+ */
+export function changedIndex(
+  schema: string,
+  table: string,
+  declared: IndexDescription,
+  held: IndexDescription,
+  detail: string,
+): DriftDifference {
+  const rebuild = (): string => {
+    const name = identifier(declared.name).text;
+    const owner = mayBeConstraintBacked(held)
+      ? `alter table ${identifier(table).text} drop constraint if exists ${name}; `
+      : '';
+    return `${owner}drop index if exists ${name}; ${createIndex(table, asDeclared(declared))}`;
+  };
+  return {
+    kind: 'changed-index',
+    table,
+    column: null,
+    cause: `index "${declared.name}" on "${table}" ${detail}, not what migrations declare`,
+    fix: statementOr(
+      schema,
+      indexNames(table, declared),
+      'drop the index this difference names and create it as the migration that declares it does',
+      rebuild,
+    ),
+  };
+}
+
+export function missingForeignKey(
+  schema: string,
+  table: string,
+  key: ForeignKeyDescription,
+): DriftDifference {
+  return {
+    kind: 'missing-foreign-key',
+    table,
+    column: null,
+    cause:
+      `table "${table}" has no foreign key on (${key.columns.join(', ')}) to ` +
+      `"${key.referencedTable}" (${key.referencedColumns.join(', ')}) that migrations declare`,
+    fix: statementOr(
+      schema,
+      [table, key.name, key.referencedTable, ...key.columns, ...key.referencedColumns],
+      'add the foreign key this difference names back, as the migration that declares it does',
+      () => addForeignKey(table, key),
+      'a row it finds is X_DB_FOREIGN_KEY_VIOLATION: repair that row, run it again, then x db migrate, which re-checks',
+    ),
+  };
+}