@ultimat3/db 9.0.0 → 10.0.0

package/CLAUDE.md

@@ -547,13 +547,35 @@ app: `create table "comments" (… references "posts" …)` before `create table
 `relation "posts" does not exist`. `down` had the mirror fault — `drop table "posts"` while
 `comments` still referenced it is `2BP01`. So `foreignKeyPlan` collects every key into a bucket of
 its own, merged into the plan **after** every table statement; `down` is reversed as a whole, so the
-drops pushed last there come out first. No topological sort and **no cycle error**: two tables
-referencing each other cannot be expressed inline in any order, and separate constraints need no
-order at all. The same call site answers the other half — a `references()` added to a column that
+drops pushed last there come out first. No topological sort and **no cycle error** *for adds*: two
+tables referencing each other cannot be expressed inline in any order, and separate constraints need
+no order at all. Dropping is not symmetrical and does need one — the paragraph below. The same call site answers the other half — a `references()` added to a column that
 already exists now emits its `add constraint`, where before `up` came out **empty**, `x db gen`
 wrote no file, and `x verify`'s drift step stayed red forever with `x db gen "…"` as a fix that did
 nothing.
 
+**Dropping a table has its own bucket, emitted BEFORE the table statements — the mirror image of
+the one above, `As of 2026-08-23`.** `--allow-destructive` emitted a bare `drop table "authors";`
+with every `alter table … drop constraint` appended AFTER it, so dropping a table another entity
+`references()` was `2BP01 cannot drop table authors because other objects depend on it` — during
+`ROLE=migrate` in the release phase, with the ledger recording nothing and a `down` of
+`-- "<table>" cannot be restored`, i.e. nothing to reverse and a generated file to hand-edit. The
+two-table case failed identically because drops came out **alphabetically**, which puts the parent
+first. Two halves. `foreignKeyPlan` routes a key whose `referencedTable` is doomed into `preDrops`
+instead of `constraints` — whether the entity still declares it or not, since a constraint cannot
+outlive its target — and its `down` is a comment, because `add constraint` against a table no
+`down` can restore is a rollback that cannot run. `drop-order.ts` orders the drops children-first
+(a self-reference is not a blocker: `drop table` takes the table's own constraints with it) and
+breaks a cycle between two doomed tables by dropping one inbound key first, which is the only
+statement it emits. The `--allow-destructive` refusal is raised over that same ordered list, so
+which table it names does not move with the alphabet.
+
+**`foreignKeyPlan` lives in `foreign-key-plan.ts`, `As of 2026-08-23`** — split out of
+`generate.ts` at the 500-line ceiling, along the seam it already drew: `generate.ts` assembles a
+plan, `foreign-key-plan.ts` decides which bucket each key statement goes in, `foreign-key.ts`
+writes the SQL. `Plan`, `foreignKeysOf` and `referenceParts` went with it because they are that
+module's vocabulary; `snapshotOf` imports `foreignKeysOf` back, one direction only.
+
 **`foreignKeyPlan` walks both directions, `As of 2026-08-19`.** 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, which `compareForeignKeys`

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ultimat3/db",
-  "version": "9.0.0",
+  "version": "10.0.0",
   "description": "Postgres access, transactions, migrations and drift detection",
   "license": "MIT",
   "type": "module",
@@ -31,7 +31,7 @@
     "test": "bun test"
   },
   "dependencies": {
-    "@ultimat3/core": "9.0.0"
+    "@ultimat3/core": "10.0.0"
   },
   "peerDependencies": {
     "@electric-sql/pglite": ">=0.5.0"

package/src/drop-order.ts

@@ -0,0 +1,61 @@
+// Single responsibility: the order a set of tables can be dropped in, and the foreign keys that
+// have to go first when no order exists. `generate.ts` writes the statements; this file decides
+// which of them may run when, because `drop table` is refused (`2BP01`) while anything still
+// points at the table.
+
+import { dropForeignKey } from './foreign-key';
+import type { TableDescription } from './introspect';
+
+export interface DropOrder {
+  /** The tables, referencing before referenced. */
+  readonly tables: readonly TableDescription[];
+  /** `drop constraint` statements that must run BEFORE the first drop — cycles only. */
+  readonly constraints: readonly string[];
+}
+
+function referencesFrom(table: TableDescription, target: string): readonly string[] {
+  return table.foreignKeys
+    .filter((key) => key.referencedTable === target)
+    .map((key) => dropForeignKey(table.name, key.name));
+}
+
+/**
+ * Drop the children first: a table nothing still-to-be-dropped points at is always safe to drop,
+ * and removing it makes its own parents safe in turn. Alphabetical order — which is what
+ * `SchemaDescription` carries — puts `authors` before `posts`, i.e. the parent first, which is the
+ * one order Postgres refuses.
+ *
+ * A self-reference is never a blocker: `drop table` takes the table's OWN constraints with it, so
+ * a tree table needs no `drop constraint` of its own.
+ *
+ * A cycle between two doomed tables has no safe order at all, so one of them is chosen and the
+ * keys pointing at it are dropped first. That is the only case that emits a statement here — every
+ * other inbound key belongs to a table that SURVIVES, which `generate.ts` handles beside the entity
+ * that still owns the column.
+ */
+export function dropOrder(dropped: readonly TableDescription[]): DropOrder {
+  const remaining = [...dropped];
+  const tables: TableDescription[] = [];
+  const constraints: string[] = [];
+  while (remaining.length > 0) {
+    const free = remaining.findIndex(
+      (table) =>
+        !remaining.some(
+          (other) =>
+            other.name !== table.name &&
+            other.foreignKeys.some((key) => key.referencedTable === table.name),
+        ),
+    );
+    const index = free === -1 ? 0 : free;
+    const next = remaining[index] as TableDescription;
+    if (free === -1) {
+      for (const other of remaining) {
+        if (other.name === next.name) continue;
+        constraints.push(...referencesFrom(other, next.name));
+      }
+    }
+    tables.push(next);
+    remaining.splice(index, 1);
+  }
+  return { tables, constraints };
+}

package/src/errors.ts

@@ -97,7 +97,6 @@ export class DbError extends UltimateError {
       code: init.code,
       cause: init.cause,
       fix: init.fix,
-      docs: `https://ultimate.dev/errors/${init.code}`,
       meta: init.meta,
       sourceError: init.sourceError,
     });

package/src/foreign-key-plan.ts

@@ -0,0 +1,146 @@
+// Single responsibility: which foreign keys a migration must add or drop, and into which of the
+// two buckets each statement goes — `constraints` runs AFTER the table statements, `preDrops`
+// 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 type { ForeignKeyDescription, TableDescription } from './introspect';
+
+/** The two directions of one migration, pushed in `up` order; `down` is reversed at assembly. */
+export interface Plan {
+  readonly up: string[];
+  readonly down: string[];
+}
+
+/**
+ * The two ends of a `references()`, which entity renders as `"<table>.<column>"`. Read once: the
+ * clause that writes the constraint and the snapshot that records it must not disagree about what
+ * it points at, or drift reports a key the database holds exactly as declared.
+ */
+export function referenceParts(references: string): readonly [string, string] {
+  const [table = references, column = 'id'] = references.split('.');
+  return [table, column];
+}
+
+/**
+ * The keys this entity declares, recorded so drift can see one dropped by hand. Recording
+ * `foreignKeys: []` while the same run emitted a constraint was a snapshot claiming a constraint
+ * does not exist that the migration beside it creates, and `compareTable` had nothing to compare —
+ * a key dropped on the database was invisible to every check the framework runs.
+ *
+ * The name is `<table>_<column>_fkey` — what Postgres would have called an inline `references`
+ * clause — and `addForeignKey` now writes it out, so the snapshot records a name the migration
+ * beside it chose rather than one it guessed. It is still *not* what drift matches on: see
+ * `compareForeignKeys` in `drift.ts`.
+ *
+ * `onDelete` is the column's own, and `addForeignKey` spells it: a rule recorded here while no
+ * clause declared one would be a claim about the database that is not true, which is what it was
+ * until the clause learned to write it out.
+ */
+export function foreignKeysOf(entity: EntityDescriptionLike): ForeignKeyDescription[] {
+  return entity.columns
+    .filter((column) => column.references !== null)
+    .map((column): ForeignKeyDescription => {
+      const [table, key] = referenceParts(column.references ?? '');
+      return {
+        name: `${entity.table}_${column.column}_fkey`,
+        columns: [column.column],
+        referencedTable: table,
+        referencedColumns: [key],
+        onDelete: column.onDelete ?? null,
+      };
+    })
+    .sort((a, b) => (a.name < b.name ? -1 : 1));
+}
+
+/**
+ * Every foreign key the entity declares that the previous snapshot does not already record, as its
+ * own `add constraint`. One call site for both cases the generator has — a table being created and
+ * a `references()` added to a column that already exists — because they are one question: which of
+ * this entity's keys does the database not hold yet.
+ *
+ * The statements land in a bucket of their own, appended after every table statement, so a key
+ * never runs before the table it points at. `down` is reversed as a whole, so pushing the drops
+ * last here puts them *first* on the way back: `drop table "posts"` with `comments` still
+ * referencing it is `2BP01`, a migration that cannot be rolled back at all.
+ *
+ * The mirror image of that asymmetry is `plans.preDrops`, which is emitted BEFORE the table
+ * statements: a key pointing at a table this migration DROPS has to go first, or the drop is
+ * `2BP01` on the way forward. Its `down` is a comment for the same reason the table's own is —
+ * `add constraint` against a table no `down` can restore is a rollback that cannot run.
+ *
+ * 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
+ * recorded, never the name this generator would have chosen — a hand-written `fk_legacy` is
+ * `42704` under the generated spelling.
+ */
+export function foreignKeyPlan(
+  entity: EntityDescriptionLike,
+  live: TableDescription | undefined,
+  plans: ConstraintPlans,
+): void {
+  const { constraints, preDrops, doomed } = plans;
+  const wanted = foreignKeysOf(entity);
+  const held = new Map((live?.foreignKeys ?? []).map((key) => [foreignKeyTarget(key), key]));
+  for (const key of wanted) {
+    const recorded = held.get(foreignKeyTarget(key));
+    if (doomed.has(key.referencedTable)) {
+      // Still declared, but its target is going away this migration. The constraint cannot outlive
+      // the table, so it goes first — and no `add constraint` is written for one that never was.
+      if (recorded !== undefined)
+        unrestorableDrop(entity.table, recorded.name, key.referencedTable, preDrops);
+      continue;
+    }
+    if (recorded === undefined) {
+      constraints.up.push(addForeignKey(entity.table, key));
+      constraints.down.push(dropForeignKey(entity.table, key.name));
+      continue;
+    }
+    // The rule is not part of a key's identity, so the same key under a new one is a rebuild —
+    // Postgres has no `alter constraint` for it, the same reason `redefineIndex` recreates.
+    if (onDeleteRule(recorded.onDelete) === onDeleteRule(key.onDelete)) continue;
+    constraints.up.push(
+      dropForeignKey(entity.table, recorded.name),
+      addForeignKey(entity.table, key),
+    );
+    // Pushed forwards and read backwards, like `redefineIndex`: `down` is reversed at assembly.
+    constraints.down.push(
+      addForeignKey(entity.table, recorded),
+      dropForeignKey(entity.table, key.name),
+    );
+  }
+  const declared = new Set(wanted.map(foreignKeyTarget));
+  const columns = new Set(entity.columns.map((column) => column.column));
+  for (const key of live?.foreignKeys ?? []) {
+    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.
+    if (!key.columns.every((column) => columns.has(column))) continue;
+    if (doomed.has(key.referencedTable)) {
+      unrestorableDrop(entity.table, key.name, key.referencedTable, preDrops);
+      continue;
+    }
+    constraints.up.push(dropForeignKey(entity.table, key.name));
+    constraints.down.push(addForeignKey(entity.table, key));
+  }
+}
+
+export interface ConstraintPlans {
+  /** `add`/`drop` for keys between tables that survive — appended AFTER the table statements. */
+  readonly constraints: Plan;
+  /** Keys pointing at a table this migration drops — emitted BEFORE the table statements. */
+  readonly preDrops: Plan;
+  /** The tables this migration drops, by name. */
+  readonly doomed: ReadonlySet<string>;
+}
+
+/** A key whose target is being dropped: gone on the way up, a note on the way back. */
+function unrestorableDrop(table: string, constraint: string, target: string, preDrops: Plan): void {
+  preDrops.up.push(dropForeignKey(table, constraint));
+  preDrops.down.push(
+    `-- constraint "${constraint}" on "${table}" cannot be restored; "${target}" is gone`,
+  );
+}

package/src/foreign-key.ts

@@ -5,14 +5,22 @@
 import { assert } from '@ultimat3/core';
 import type { ForeignKeyDescription } from './introspect';
 
-/** `pg_constraint.confdeltype`. The catalog's vocabulary; a description holds the rule's name. */
-const CATALOG_RULES: Readonly<Record<string, string>> = {
-  a: 'no action',
-  c: 'cascade',
-  r: 'restrict',
-  n: 'set null',
-  d: 'set default',
-};
+/**
+ * `pg_constraint.confdeltype`. The catalog's vocabulary; a description holds the rule's name.
+ *
+ * A `Map`, because `raw` is a catalog string on every read: an object literal answered
+ * `CATALOG_RULES['constructor']` with the `Object` FUNCTION, which left this `string | null`
+ * function returning one into `compareForeignKeys`.
+ */
+const CATALOG_RULES: ReadonlyMap<string, string> = new Map(
+  Object.entries({
+    a: 'no action',
+    c: 'cascade',
+    r: 'restrict',
+    n: 'set null',
+    d: 'set default',
+  }),
+);
 
 /**
  * One `on delete` vocabulary for both sides. The catalog spells the rule as a single character and
@@ -25,7 +33,7 @@ const CATALOG_RULES: Readonly<Record<string, string>> = {
  */
 export function onDeleteRule(raw: string | null): string | null {
   if (raw === null) return null;
-  const named = CATALOG_RULES[raw] ?? raw.toLowerCase();
+  const named = CATALOG_RULES.get(raw) ?? raw.toLowerCase();
   return named === 'no action' ? null : named;
 }
 

package/src/generate.ts

@@ -5,16 +5,16 @@
 
 import { assert, systemClock } from '@ultimat3/core';
 import { isDestructive } from './destructive';
+import { dropOrder } from './drop-order';
 import type {
   ColumnDescriptionLike,
   EntityDescriptionLike,
   IndexDescriptionLike,
 } from './entity-shape';
 import { migrationIrreversible } from './errors';
-import { addForeignKey, dropForeignKey, foreignKeyTarget, onDeleteRule } from './foreign-key';
+import { type ConstraintPlans, foreignKeyPlan, foreignKeysOf, type Plan } from './foreign-key-plan';
 import {
   type ColumnDescription,
-  type ForeignKeyDescription,
   findTable,
   type IndexDescription,
   type SchemaDescription,
@@ -52,16 +52,6 @@ function defaultExpression(column: ColumnDescriptionLike): string | null {
   return null;
 }
 
-/**
- * The two ends of a `references()`, which entity renders as `"<table>.<column>"`. Read once: the
- * clause that writes the constraint and the snapshot that records it must not disagree about what
- * it points at, or drift reports a key the database holds exactly as declared.
- */
-function referenceParts(references: string): readonly [string, string] {
-  const [table = references, column = 'id'] = references.split('.');
-  return [table, column];
-}
-
 function columnClause(column: ColumnDescriptionLike): string {
   const parts = [`"${column.column}"`, sqlType(column.kind)];
   const expression = defaultExpression(column);
@@ -103,37 +93,6 @@ function impliedByColumnClause(
   return column !== undefined && column.unique && !column.primaryKey && added.has(only);
 }
 
-/**
- * The keys this entity declares, recorded so drift can see one dropped by hand. Recording
- * `foreignKeys: []` while the same run emitted a constraint was a snapshot claiming a constraint
- * does not exist that the migration beside it creates, and `compareTable` had nothing to compare —
- * a key dropped on the database was invisible to every check the framework runs.
- *
- * The name is `<table>_<column>_fkey` — what Postgres would have called an inline `references`
- * clause — and `addForeignKey` now writes it out, so the snapshot records a name the migration
- * beside it chose rather than one it guessed. It is still *not* what drift matches on: see
- * `compareForeignKeys` in `drift.ts`.
- *
- * `onDelete` is the column's own, and `addForeignKey` spells it: a rule recorded here while no
- * clause declared one would be a claim about the database that is not true, which is what it was
- * until the clause learned to write it out.
- */
-function foreignKeysOf(entity: EntityDescriptionLike): ForeignKeyDescription[] {
-  return entity.columns
-    .filter((column) => column.references !== null)
-    .map((column): ForeignKeyDescription => {
-      const [table, key] = referenceParts(column.references ?? '');
-      return {
-        name: `${entity.table}_${column.column}_fkey`,
-        columns: [column.column],
-        referencedTable: table,
-        referencedColumns: [key],
-        onDelete: column.onDelete ?? null,
-      };
-    })
-    .sort((a, b) => (a.name < b.name ? -1 : 1));
-}
-
 export function snapshotOf(entities: readonly EntityDescriptionLike[]): SchemaDescription {
   const tables = [...entities]
     .sort((a, b) => (a.table < b.table ? -1 : 1))
@@ -202,69 +161,6 @@ function createIndex(table: string, index: IndexDescriptionLike): string {
   return `${kind} "${index.name}" on "${table}" (${columns})${predicate};`;
 }
 
-interface Plan {
-  readonly up: string[];
-  readonly down: string[];
-}
-
-/**
- * Every foreign key the entity declares that the previous snapshot does not already record, as its
- * own `add constraint`. One call site for both cases the generator has — a table being created and
- * a `references()` added to a column that already exists — because they are one question: which of
- * this entity's keys does the database not hold yet.
- *
- * The statements land in a bucket of their own, appended after every table statement, so a key
- * never runs before the table it points at. `down` is reversed as a whole, so pushing the drops
- * last here puts them *first* on the way back: `drop table "posts"` with `comments` still
- * referencing it is `2BP01`, a migration that cannot be rolled back at all.
- *
- * 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
- * recorded, never the name this generator would have chosen — a hand-written `fk_legacy` is
- * `42704` under the generated spelling.
- */
-function foreignKeyPlan(
-  entity: EntityDescriptionLike,
-  live: TableDescription | undefined,
-  constraints: Plan,
-): void {
-  const wanted = foreignKeysOf(entity);
-  const held = new Map((live?.foreignKeys ?? []).map((key) => [foreignKeyTarget(key), key]));
-  for (const key of wanted) {
-    const recorded = held.get(foreignKeyTarget(key));
-    if (recorded === undefined) {
-      constraints.up.push(addForeignKey(entity.table, key));
-      constraints.down.push(dropForeignKey(entity.table, key.name));
-      continue;
-    }
-    // The rule is not part of a key's identity, so the same key under a new one is a rebuild —
-    // Postgres has no `alter constraint` for it, the same reason `redefineIndex` recreates.
-    if (onDeleteRule(recorded.onDelete) === onDeleteRule(key.onDelete)) continue;
-    constraints.up.push(
-      dropForeignKey(entity.table, recorded.name),
-      addForeignKey(entity.table, key),
-    );
-    // Pushed forwards and read backwards, like `redefineIndex`: `down` is reversed at assembly.
-    constraints.down.push(
-      addForeignKey(entity.table, recorded),
-      dropForeignKey(entity.table, key.name),
-    );
-  }
-  const declared = new Set(wanted.map(foreignKeyTarget));
-  const columns = new Set(entity.columns.map((column) => column.column));
-  for (const key of live?.foreignKeys ?? []) {
-    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.
-    if (!key.columns.every((column) => columns.has(column))) continue;
-    constraints.up.push(dropForeignKey(entity.table, key.name));
-    constraints.down.push(addForeignKey(entity.table, key));
-  }
-}
-
 /**
  * Skipping an existing column by name alone missed the type moving under it: a table created
  * while money's currency was bare `char` keeps `char(1)` and rejects every ISO 4217 code, yet the
@@ -405,11 +301,19 @@ export function generateMigration(options: GenerateOptions): GeneratedMigration
   const plan: Plan = { up: [], down: [] };
   // Merged into `plan` once every table statement is in, never interleaved with them.
   const constraints: Plan = { up: [], down: [] };
+  // Merged in BEFORE them, for the mirror-image reason: a key still pointing at a table this
+  // migration drops makes that `drop table` `2BP01`.
+  const preDrops: Plan = { up: [], down: [] };
   const wanted = new Set(options.entities.map((entity) => entity.table));
 
+  const doomed = new Set(
+    current.tables.filter((table) => !wanted.has(table.name)).map((table) => table.name),
+  );
+  const plans: ConstraintPlans = { constraints, preDrops, doomed };
+
   for (const entity of options.entities) {
     const live = findTable(current, entity.table);
-    foreignKeyPlan(entity, live, constraints);
+    foreignKeyPlan(entity, live, plans);
     if (live === undefined) {
       plan.up.push(...createTable(entity));
       plan.down.push(`drop table "${entity.table}";`);
@@ -433,14 +337,18 @@ export function generateMigration(options: GenerateOptions): GeneratedMigration
     }
   }
 
-  for (const table of current.tables) {
-    if (wanted.has(table.name)) continue;
+  const order = dropOrder(current.tables.filter((table) => !wanted.has(table.name)));
+  for (const table of order.tables) {
     if (options.allowDestructive !== true) {
       throw migrationIrreversible(
         `dropping table "${table.name}" discards every row and cannot be undone`,
         `x db gen "${options.name}" --allow-destructive   # or delete the entity in two releases`,
       );
     }
+  }
+  plan.up.push(...preDrops.up, ...order.constraints);
+  plan.down.push(...preDrops.down, ...order.constraints.map(() => '-- constraint not restored'));
+  for (const table of order.tables) {
     plan.up.push(`drop table "${table.name}";`);
     plan.down.push(`-- "${table.name}" cannot be restored; recover it from a backup`);
   }

package/src/sql.ts

@@ -135,6 +135,13 @@ export function identifier(name: string): SqlFragment {
  * A quoted string literal. Postgres utility statements (`CREATE DATABASE`, `COMMENT ON`) reject
  * bound parameters, so this is the only place a value may be inlined — and it escapes quotes.
  * Never reach for it in a query: `sql` binds parameters there.
+ *
+ * The doubling is only an escape while `standard_conforming_strings` is `on`, which has been the
+ * server default since 9.1: with it OFF, a backslash escapes the quote that follows and a value
+ * ending in one closes the literal early. So this is safe for framework-supplied names — a
+ * database, a schema, a comment this repo writes — and is NOT an escape for untrusted text under
+ * an arbitrary server configuration. Nothing passes it caller input today; if something must,
+ * bind a parameter instead, or send `E''`-style quoting from a statement that can take one.
  */
 export function literal(value: string): SqlFragment {
   return raw(`'${value.replaceAll("'", "''")}'`);