@ultimat3/db 14.0.0 → 16.0.0

package/src/drift.ts

@@ -4,198 +4,35 @@
 // by the framework contract; `x verify` fails on it and `--json` carries every difference.
 
 import { baseClient, type DbClient } from './client';
+import type { DriftDifference } from './drift-findings';
+import {
+  changedColumn,
+  changedForeignKey,
+  changedIndex,
+  missingCheck,
+  missingColumn,
+  missingForeignKey,
+  missingIndex,
+  missingTable,
+  unexpectedColumn,
+  unexpectedTable,
+  unknownSchema,
+} from './drift-findings';
 import { DbError } from './errors';
-import { foreignKeyTarget, onDeleteRule, rebuildForeignKey } from './foreign-key';
+import { foreignKeyTarget, onDeleteRule } from './foreign-key';
 import { indexMethodOf } from './index-method';
-import {
-  type ForeignKeyDescription,
-  findTable,
-  introspect,
-  type SchemaDescription,
-  type TableDescription,
-} from './introspect';
+import { findTable, introspect, type SchemaDescription, type TableDescription } from './introspect';
 import { type LedgerRow, type Migration, readLedger } from './migrate';
 
-export type DriftKind =
-  | 'unexpected-column'
-  | 'missing-column'
-  | 'changed-column'
-  | 'unexpected-table'
-  | 'missing-table'
-  | 'unknown-schema'
-  | 'missing-index'
-  | 'changed-index'
-  | 'missing-foreign-key'
-  | 'changed-foreign-key';
-
-export interface DriftDifference {
-  readonly kind: DriftKind;
-  readonly table: string;
-  readonly column: string | null;
-  readonly cause: string;
-  readonly fix: string;
-}
+// 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.
+export type { DriftDifference, DriftKind } from './drift-findings';
 
 export interface DriftReport {
   readonly ok: boolean;
   readonly differences: readonly DriftDifference[];
 }
 
-function unexpectedColumn(table: string, column: string): DriftDifference {
-  return {
-    kind: 'unexpected-column',
-    table,
-    column,
-    // Pinned by the contract. Do not reword without changing docs/errors/X_DB_DRIFT.
-    cause: `table "${table}" has column "${column}" not present in any migration`,
-    fix: `x db gen "add ${column}"`,
-  };
-}
-
-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',
-  };
-}
-
-/**
- * The column exists on both sides and one of them lets it be `NULL`.
- *
- * This is the finding the expand/contract flow needs and never had. `generate.ts` emits a `NOT
- * NULL` add as nullable plus a `-- backfill "c", then: … set not null;` comment, because the
- * strict version cannot succeed on a populated table — and phase 2 is a comment, so it is a thing
- * a human has to remember. Nobody did, and `compareTable` compared columns by name and by type
- * while `snapshotOf` had recorded `nullable` all along, so the column stayed nullable forever
- * against an entity schema that said otherwise, with `ok: true` on every check. The first
- * `undefined` write then lands as `NULL` and crashes three services away from the migration.
- *
- * `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.
- */
-function changedColumn(table: string, column: string, liveNullable: boolean): DriftDifference {
-  const clause = liveNullable ? 'set not null' : 'drop not null';
-  return {
-    kind: 'changed-column',
-    table,
-    column,
-    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`,
-    fix:
-      `alter table "${table}" alter column "${column}" ${clause};   # in a new migration` +
-      (liveNullable ? ' — backfill the existing NULLs first' : ''),
-  };
-}
-
-function unexpectedTable(table: string): DriftDifference {
-  return {
-    kind: 'unexpected-table',
-    table,
-    column: null,
-    cause: `table "${table}" is not present in any migration`,
-    fix: `x db gen "add ${table}"`,
-  };
-}
-
-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"
- * because it had nothing to check is the one failure mode drift detection cannot have.
- */
-function unknownSchema(migrations: readonly Migration[]): DriftDifference {
-  const newest = [...migrations].sort((a, b) => (a.id < b.id ? -1 : 1)).at(-1);
-  return {
-    kind: 'unknown-schema',
-    table: '',
-    column: null,
-    cause:
-      `migration "${newest?.id ?? ''}" records no schema snapshot, so what this database owes ` +
-      'cannot be established',
-    // The same two remedies `X_MIGRATION_SNAPSHOT_MISSING` names, in the same order, because it is
-    // the same condition. It used to lead with `x db gen`, which raises that error and whose own
-    // fix pointed back here — a cycle a scaffolded app hit on its first `x db migrate`. The
-    // pathspec is a glob because this package is tier 1: only `@ultimat3/cli` knows the directory.
-    fix:
-      `git checkout -- "*${newest?.id ?? ''}.snapshot.json"   # or, if it was never written: ` +
-      `delete migration "${newest?.id ?? ''}" and rerun x db gen "${newest?.name ?? 'initial'}"`,
-  };
-}
-
-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',
-  };
-}
-
-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',
-  };
-}
-
-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
- * 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`.
- */
-function changedForeignKey(
-  table: string,
-  declared: ForeignKeyDescription,
-  held: ForeignKeyDescription,
-): DriftDifference {
-  const rule = onDeleteRule(held.onDelete);
-  return {
-    kind: 'changed-foreign-key',
-    table,
-    column: null,
-    cause:
-      `foreign key 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`,
-  };
-}
-
 /**
  * Indexes migrations declare, against the ones the catalog holds — by column list and by
  * uniqueness, which is what caught a composite index rebuilt with its columns the other way round
@@ -314,6 +151,33 @@ function compareForeignKeys(live: TableDescription, expected: TableDescription):
   return differences;
 }
 
+/**
+ * CHECK constraints migrations declare, against the NAMES the catalog holds — `checkNames`, which
+ * is a separate field from `checks` precisely so this comparison cannot reach a definition it must
+ * not read (`introspect.ts`).
+ *
+ * Two absences, and they mean opposite things. `expected.checks` absent is a sidecar written
+ * before constraints were recorded: it declares nothing, so nothing can be missing. `live.checkNames`
+ * absent is a description that never asked the catalog — a stub, a fake client's rows, a
+ * `TableDescription` built by hand — and reading that as "the database holds none" is one finding
+ * per declared constraint against a database nobody looked at. `introspect()` always answers with
+ * the field, `[]` included, so a real read is never mistaken for an unread one.
+ *
+ * Only the declared side is judged, the rule `compareIndexes` and `compareForeignKeys` both state:
+ * a NOT NULL, an `enumerated()` column's old anonymous form, a constraint an extension brought and
+ * every hand-written CHECK an app has ever added would each be a finding against a database that
+ * is exactly right.
+ */
+function compareChecks(live: TableDescription, expected: TableDescription): DriftDifference[] {
+  const declared = expected.checks;
+  const held = live.checkNames;
+  if (declared === undefined || held === undefined) return [];
+  const present = new Set(held);
+  return declared
+    .filter((check) => !present.has(check.name))
+    .map((check) => missingCheck(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
@@ -350,6 +214,7 @@ function compareTable(live: TableDescription, expected: TableDescription): Drift
     }
   }
   differences.push(...compareIndexes(live, expected));
+  differences.push(...compareChecks(live, expected));
   differences.push(...compareForeignKeys(live, expected));
   return differences;
 }

package/src/errors.ts

@@ -11,7 +11,6 @@ import {
   stringField,
   UltimateError,
 } from '@ultimat3/core';
-import { DESTRUCTIVE_CAUSE, DESTRUCTIVE_MARKER, type DestructiveStatement } from './destructive';
 import { type DbSqlStateCode, sqlState, sqlStateCode } from './sqlstate';
 
 /**
@@ -31,6 +30,7 @@ export const DB_OWNED_ERROR_CODES = [
   'X_MIGRATION_IRREVERSIBLE',
   'X_MIGRATION_DESTRUCTIVE',
   'X_MIGRATION_SNAPSHOT_MISSING',
+  'X_MIGRATION_VIEW_DEPENDS',
   'X_MIGRATE_CONCURRENT',
   'X_SQL_UNSAFE',
   'X_BRANCH_EXISTS',
@@ -72,6 +72,7 @@ export const DB_ERROR_TITLES: Readonly<Record<DbOwnedErrorCode, string>> = {
   X_MIGRATION_IRREVERSIBLE: 'this migration cannot be reversed without data loss',
   X_MIGRATION_DESTRUCTIVE: 'this migration destroys data and does not say so',
   X_MIGRATION_SNAPSHOT_MISSING: 'the newest migration records no schema snapshot',
+  X_MIGRATION_VIEW_DEPENDS: 'a view is compiled against a column this migration retypes',
   X_SQL_UNSAFE: 'SQL was built by string interpolation',
   X_BRANCH_EXISTS: 'that branch database already exists',
 };
@@ -284,26 +285,6 @@ export const serializationExhausted = (attempts: number, sourceError: unknown):
     sourceError,
   });
 
-/**
- * The migration advisory lock was still held when the wait ran out. `pg_advisory_lock` blocks with
- * no timeout, so a migrator wedged on a partition — or OOM-killed with its backend still alive —
- * left `helm upgrade --wait` sitting inside one statement, printing nothing, with the job never
- * failing so `backoffLimit` never fired. A bounded `pg_try_advisory_lock` poll turns that into an
- * exit code.
- */
-export const migrateConcurrent = (lockKey: number, waitedMs: number): DbError =>
-  new DbError({
-    code: 'X_MIGRATE_CONCURRENT',
-    cause:
-      `another session still holds pg_advisory_lock(${lockKey}) after waiting ${waitedMs}ms, ` +
-      'so this migrator refused rather than block a deploy forever',
-    fix:
-      'psql "$DATABASE_URL" -c "select pid, application_name, state from pg_stat_activity ' +
-      "join pg_locks using (pid) where locktype = 'advisory'\"" +
-      '   # pg_terminate_backend(pid) the wedged migrator, then: x db migrate',
-    meta: { lockKey, waitedMs },
-  });
-
 /** The contract's pinned wording. Mirror of `@ultimat3/entity`'s `dbDrift()` — keep in sync. */
 export const dbDrift = (tableName: string, columnName: string): DbError =>
   new DbError({
@@ -313,85 +294,6 @@ export const dbDrift = (tableName: string, columnName: string): DbError =>
     meta: { table: tableName, column: columnName },
   });
 
-export const migrationConflict = (cause: string, fix: string): DbError =>
-  new DbError({ code: 'X_MIGRATION_CONFLICT', cause, fix });
-
-export const migrationIrreversible = (cause: string, fix: string): DbError =>
-  new DbError({ code: 'X_MIGRATION_IRREVERSIBLE', cause, fix });
-
-/**
- * A rollback step count this build cannot honour. `steps` reaches `Array.prototype.slice`, where a
- * negative count counts from the END: `steps: -1` selected every applied migration except the
- * newest and reversed four of five, which is the one class of mistake a rollback cannot undo.
- * Refused rather than coerced, exactly as `DATABASE_POOL_MAX` is — a number silently reinterpreted
- * as a different one is the failure a validated argument exists to prevent.
- */
-export const rollbackStepsInvalid = (received: number): DbError =>
-  new DbError({
-    code: 'X_INVARIANT',
-    cause: `rollback was asked to reverse ${String(received)} migrations, which is not a positive integer`,
-    fix: 'rollback({ migrations, steps: 1 })   # a whole number of migrations, newest first',
-    meta: { steps: received },
-  });
-
-/**
- * `packages/db/migrations/0000_initial.snapshot.json` → `packages/db/migrations/0000_initial.*` —
- * every file that one migration owns, as one `rm` argument. Derived from the path the caller passed
- * rather than rebuilt from a directory this package does not know: `db` is tier 1 and where an app
- * keeps its migrations is `@ultimat3/cli`'s answer, not this one's.
- */
-const snapshotSiblings = (file: string): string => file.replace(/\.snapshot\.json$/, '.*');
-
-/**
- * `20260817120000_add_posts` → `add_posts`, the argument `x db gen` takes. The name is free text
- * and only ever labels a *new* id, so an id carrying no stamp answers with itself rather than with
- * the empty string — a `fix:` ending in `x db gen ""` is a command that cannot be run.
- */
-const migrationNameOf = (id: string): string => id.replace(/^\d+_/, '') || id;
-
-/**
- * The sidecar every generated migration writes is what the *next* generation diffs against, so a
- * newest migration without one leaves nothing to diff. Refused rather than defaulted to the empty
- * schema, which would generate `create table` for every table the database already holds.
- */
-export const migrationSnapshotMissing = (id: string, file: string): DbError =>
-  new DbError({
-    code: 'X_MIGRATION_SNAPSHOT_MISSING',
-    cause: `migration "${id}" records no schema snapshot (${file}), so there is nothing to diff against`,
-    // Two remedies, both commands, in the order they are safe to try. "restore from version
-    // control" alone was neither: on a scaffolded app the sidecar was never written, so there is
-    // nothing to restore — and the drift this refusal answers named `x db gen` as *its* fix, so
-    // the two errors pointed at each other and an app's first migration had no way out.
-    // `x db gen` is named only *after* the files it would trip over are gone.
-    fix:
-      `git checkout -- ${file}   # or, if it was never written: ` +
-      `rm ${snapshotSiblings(file)} && x db gen "${migrationNameOf(id)}"`,
-    meta: { id, file },
-  });
-
-/**
- * One error per file, never one per statement: the marker declares the whole migration, so a
- * second finding would repeat an instruction the first already gave. `file` is app-relative and
- * arrives from the caller — `db` is tier 1 and does not know where an app keeps its migrations.
- *
- * Irreversible and destructive are two questions. `X_MIGRATION_IRREVERSIBLE` refuses to *generate*
- * a plan whose `down` cannot restore the rows; this one refuses to *ship* a plan whose `up`
- * destroys them without saying so — a retype is reversible in DDL and still rewrites every row.
- */
-export const migrationDestructive = (
-  file: string,
-  first: DestructiveStatement,
-  more = 0,
-): DbError =>
-  new DbError({
-    code: 'X_MIGRATION_DESTRUCTIVE',
-    cause:
-      `${file} ${DESTRUCTIVE_CAUSE[first.kind]} and does not declare it` +
-      `${more === 0 ? '' : ` (and ${more} more destructive)`}: ${first.statement}`,
-    fix: `add the line "${DESTRUCTIVE_MARKER}" to ${file}, or regenerate it: x db gen "<name>" --allow-destructive`,
-    meta: { file, kind: first.kind, statements: more + 1 },
-  });
-
 export const sqlUnsafe = (received: string, position: number): DbError =>
   new DbError({
     code: 'X_SQL_UNSAFE',

package/src/foreign-key-plan.ts

@@ -3,9 +3,15 @@
 // BEFORE them. `generate.ts` assembles the plan; `foreign-key.ts` writes the SQL.
 
 import type { EntityDescriptionLike } from './entity-shape';
-import { addForeignKey, dropForeignKey, foreignKeyTarget, onDeleteRule } from './foreign-key';
+import {
+  addForeignKey,
+  dropForeignKey,
+  foreignKeyTarget,
+  keyId,
+  onDeleteRule,
+  unrestorableNote,
+} from './foreign-key';
 import type { ForeignKeyDescription, TableDescription } from './introspect';
-import { identifier } from './sql';
 
 /** The two directions of one migration, pushed in `up` order; `down` is reversed at assembly. */
 export interface Plan {
@@ -73,19 +79,31 @@ export function foreignKeysOf(entity: EntityDescriptionLike): ForeignKeyDescript
  * Both directions, because a snapshot may not lie: a removed `references()` used to emit nothing
  * while the snapshot beside it recorded `foreignKeys: []`, so the orphan constraint stayed on the
  * database *and* the record denied one the catalog holds — and `compareForeignKeys` judges the
- * declared side, so no drift check could ever see it. Not parity with a removed index either: that
- * leaves the snapshot correct by omission. The drop names the constraint the previous snapshot
+ * declared side, so no drift check could ever see it. This comment used to add "not parity with a
+ * removed index either: that leaves the snapshot correct by omission", which was **wrong** — a
+ * removed index lied in the identical way, and `index-plan.ts` is the arm that closed it. The drop names the constraint the previous snapshot
  * recorded, never the name this generator would have chosen — a hand-written `fk_legacy` is
  * `42704` under the generated spelling.
+ *
+ * `plans.predropped` names the constraints a RETYPE already took out of the way (`retype-keys.ts`),
+ * and it is read as "the schema does not record this key" — the same reading `checkPlan` gives its
+ * own `predropped` set. That is what makes this function the one writer of an `add constraint`
+ * after a retype: a key still declared is added back here, in the bucket that already runs after
+ * every table statement; one the entity dropped is left where the retype left it, because dropping
+ * it a second time is `42704`; and one whose `on delete` moved comes back carrying the new rule.
+ * Its `down` is the retype's, pushed where reversal puts it after both ends are back.
  */
 export function foreignKeyPlan(
   entity: EntityDescriptionLike,
   live: TableDescription | undefined,
   plans: ConstraintPlans,
 ): void {
-  const { constraints, preDrops, doomed } = plans;
+  const { constraints, preDrops, doomed, predropped } = plans;
   const wanted = foreignKeysOf(entity);
-  const held = new Map((live?.foreignKeys ?? []).map((key) => [foreignKeyTarget(key), key]));
+  const recordedKeys = (live?.foreignKeys ?? []).filter(
+    (key) => !predropped.has(keyId(entity.table, key.name)),
+  );
+  const held = new Map(recordedKeys.map((key) => [foreignKeyTarget(key), key]));
   for (const key of wanted) {
     const recorded = held.get(foreignKeyTarget(key));
     if (doomed.has(key.referencedTable)) {
@@ -115,7 +133,7 @@ export function foreignKeyPlan(
   }
   const declared = new Set(wanted.map(foreignKeyTarget));
   const columns = new Set(entity.columns.map((column) => column.column));
-  for (const key of live?.foreignKeys ?? []) {
+  for (const key of recordedKeys) {
     if (declared.has(foreignKeyTarget(key))) continue;
     // `drop column` takes the constraint with it, so a `drop constraint` after that statement is
     // `42704` on a constraint that is already gone.
@@ -136,19 +154,22 @@ export interface ConstraintPlans {
   readonly preDrops: Plan;
   /** The tables this migration drops, by name. */
   readonly doomed: ReadonlySet<string>;
+  /**
+   * Recorded keys a retype already dropped ahead of the ALTERs, by `keyId` (`retype-keys.ts`).
+   * Read as "not recorded", never as "leave it alone": the declared side still needs its
+   * `add constraint`, and it is this function that writes it.
+   */
+  readonly predropped: ReadonlySet<string>;
 }
 
 /**
  * A key whose target is being dropped: gone on the way up, a note on the way back.
  *
- * The note goes through `identifier` too. A `--` comment ends at the first newline, so a name
- * holding one is a second command on the line after it — the same escape `columnClause` closed,
- * one quoting rule short of the statement above it.
+ * The note itself is `unrestorableNote` (`foreign-key.ts`) and not a string built here —
+ * `retype-keys.ts` says the same thing about the same failed rollback, and two spellings of one
+ * fact is whichever module emitted last deciding what an operator reads.
  */
 function unrestorableDrop(table: string, constraint: string, target: string, preDrops: Plan): void {
   preDrops.up.push(dropForeignKey(table, constraint));
-  preDrops.down.push(
-    `-- constraint ${identifier(constraint).text} on ${identifier(table).text} ` +
-      `cannot be restored; ${identifier(target).text} is gone`,
-  );
+  preDrops.down.push(unrestorableNote(table, constraint, target));
 }

package/src/foreign-key.ts

@@ -52,6 +52,19 @@ export function foreignKeyTarget(key: ForeignKeyDescription): string {
   return JSON.stringify([[...key.columns], key.referencedTable, [...key.referencedColumns]]);
 }
 
+/**
+ * Which constraint, on which table — a key's NAME, where `foreignKeyTarget` is its meaning.
+ *
+ * The two exist for opposite questions and neither substitutes for the other. Drift asks whether
+ * two keys point the same way and must ignore the name; a plan that has already DROPPED a
+ * constraint asks whether this is that exact constraint, which is the name and nothing else. The
+ * table is in it because two tables may each hold a `..._org_id_fkey`, and `checkPlan`'s
+ * `predropped` set is the same shape one file over.
+ */
+export function keyId(table: string, constraint: string): string {
+  return JSON.stringify([table, constraint]);
+}
+
 /**
  * Through `identifier`, never `"${…}"` — the package's one rule, which every name this file writes
  * now goes through. A name that closes its own quote produced a real `drop table` through
@@ -98,6 +111,26 @@ export function dropForeignKey(table: string, constraint: string): string {
   return `alter table ${identifier(table).text} drop constraint ${identifier(constraint).text};`;
 }
 
+/**
+ * What a `down` says in place of an `add constraint` it cannot run: the key's table or its target
+ * is dropped by this migration, so there is nothing to add the constraint back onto.
+ *
+ * ONE text, two writers — `foreign-key-plan.ts`'s `unrestorableDrop` (a key pointing at a doomed
+ * table) and `retype-keys.ts`'s `restore` (a key a retype moved aside whose ends are doomed).
+ * They spelled the same fact two ways and had already drifted, so an operator reading a failed
+ * rollback saw whichever module emitted last. It lives here because both import this module and
+ * neither imports the other.
+ *
+ * Every name goes through `identifier`, including `gone`: a `--` comment ends at the first
+ * newline, so a name holding one puts a second command on the line after it.
+ */
+export function unrestorableNote(table: string, constraint: string, gone: string): string {
+  return (
+    `-- constraint ${identifier(constraint).text} on ${identifier(table).text} ` +
+    `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.