@ultimat3/db 15.0.0 → 17.0.0

package/src/drift-findings.ts

@@ -14,6 +14,7 @@
 import { onDeleteRule, rebuildForeignKey } from './foreign-key';
 import type { CheckDescription, ForeignKeyDescription } from './introspect';
 import type { Migration } from './migrate';
+import { shellInertIdentifier } from './sql';
 
 export type DriftKind =
   | 'unexpected-column'
@@ -41,6 +42,15 @@ export interface DriftReport {
   readonly differences: readonly DriftDifference[];
 }
 
+/**
+ * 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
+ * — and the argument is a migration DESCRIPTION, not an identifier, so there is no quoted form
+ * that would make a hostile name safe to pass. A name `shellInertIdentifier` (`sql.ts`) refuses
+ * is therefore left out of the command rather than escaped into it: the command still runs and
+ * still generates the migration, and the name is read off `cause` and `column`, which are prose
+ * nobody pastes.
+ */
 export function unexpectedColumn(table: string, column: string): DriftDifference {
   return {
     kind: 'unexpected-column',
@@ -48,7 +58,12 @@ export function unexpectedColumn(table: string, column: string): DriftDifference
     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}"`,
+    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}"`,
   };
 }
 
@@ -82,6 +97,8 @@ export function changedColumn(
   liveNullable: boolean,
 ): DriftDifference {
   const clause = liveNullable ? 'set not null' : 'drop not null';
+  const relation = shellInertIdentifier(table);
+  const attribute = shellInertIdentifier(column);
   return {
     kind: 'changed-column',
     table,
@@ -89,19 +106,47 @@ 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.
     fix:
-      `alter table "${table}" alter column "${column}" ${clause};   # in a new migration` +
-      (liveNullable ? ' — backfill the existing NULLs first' : ''),
+      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' : ''),
   };
 }
 
+/**
+ * The `fix:` names the two edits that actually resolve this, and neither is `x db gen` (issue
+ * #345). That command diffs the ENTITY REGISTRY against the newest snapshot, and a table nothing
+ * declares is absent from both sides of that diff — so it wrote an EMPTY migration, and the
+ * generator's own empty-diff branch writes no file at all, leaving the reader with nothing to run
+ * and the same finding on the next deploy.
+ *
+ * What is left once `@ultimat3/cli`'s `acceptCreatedTables` has run is a table no migration's SQL
+ * creates and no entity declares — so either a migration should claim it (`if not exists`, because
+ * 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.
+ */
 export function unexpectedTable(table: string): DriftDifference {
+  const name = shellInertIdentifier(table);
   return {
     kind: 'unexpected-table',
     table,
     column: null,
     cause: `table "${table}" is not present in any migration`,
-    fix: `x db gen "add ${table}"`,
+    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"`,
   };
 }
 
@@ -174,6 +219,8 @@ export function changedIndex(table: string, index: string, detail: string): Drif
  * the predicate, which is what makes an executable fix possible at all.
  */
 export function missingCheck(table: string, check: CheckDescription): DriftDifference {
+  const relation = shellInertIdentifier(table);
+  const constraint = shellInertIdentifier(check.name);
   return {
     kind: 'missing-check',
     table,
@@ -183,9 +230,19 @@ export function missingCheck(table: string, check: CheckDescription): DriftDiffe
     // 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.
     fix:
-      `alter table "${table}" add constraint "${check.name}" ` +
-      `check (${check.expression});   # in a new migration, then x db migrate`,
+      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`,
   };
 }
 

package/src/drift-fixtures.ts

@@ -0,0 +1,23 @@
+// TEST-ONLY. The two builders every drift suite compares with — a `TableDescription` of text
+// columns and the `SchemaDescription` around it. One copy, because three suites arguing about
+// schemas built differently would each be judging a different fixture. Never exported from
+// `index.ts`.
+
+import type { SchemaDescription, TableDescription } from './introspect';
+
+export const table = (name: string, columns: readonly string[]): TableDescription => ({
+  schema: 'public',
+  name,
+  columns: columns.map((column, index) => ({
+    name: column,
+    dataType: 'text',
+    nullable: true,
+    default: null,
+    position: index + 1,
+  })),
+  primaryKey: ['id'],
+  indexes: [],
+  foreignKeys: [],
+});
+
+export const schema = (...tables: readonly TableDescription[]): SchemaDescription => ({ tables });

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,114 +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({
-    code: 'X_DB_DRIFT',
-    cause: `table "${tableName}" has column "${columnName}" not present in any migration`,
-    fix: `x db gen "add ${columnName}"`,
-    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.

package/src/generate.ts

@@ -9,11 +9,11 @@ import { defaultExpression } from './column-default';
 import { isDestructive } from './destructive';
 import { dropOrder } from './drop-order';
 import type { ColumnDescriptionLike, EntityDescriptionLike } from './entity-shape';
-import { migrationIrreversible } from './errors';
 import { type ConstraintPlans, foreignKeyPlan, foreignKeysOf, type Plan } from './foreign-key-plan';
 import type { Regeneration } from './generated-column';
 import { generatedClause, isGenerated, regenerate } from './generated-column';
-import { createIndex, dropIndex, impliedByColumnClause, redefineIndex } from './index-ddl';
+import { createIndex, impliedByColumnClause } from './index-ddl';
+import { indexPlan } from './index-plan';
 import {
   type ColumnDescription,
   findTable,
@@ -21,31 +21,14 @@ import {
   type TableDescription,
 } from './introspect';
 import { declaredIndexes } from './invariant-ddl';
+import { migrationIrreversible } from './migration-errors';
 import type { MovedAside } from './retype-dependents';
 import { moveDependentsAside } from './retype-dependents';
+import { moveKeysAside, retypedColumns, retypedIn } from './retype-keys';
 import { identifier } from './sql';
+import { sqlType } from './sql-type';
 import { type UnrenderedDeclaration, unrenderedComment, unrenderedOf } from './unrendered';
 
-const SQL_TYPES: Readonly<Record<string, string>> = {
-  uuid: 'uuid',
-  text: 'text',
-  // Bare `char` is `char(1)` in Postgres, and the only column carrying this kind is money's
-  // currency — a three-letter ISO 4217 code whose CHECK the entity emits on the same line.
-  // Without the length no currency ever fits the constraint the same statement demands.
-  char: 'char(3)',
-  boolean: 'boolean',
-  integer: 'integer',
-  bigint: 'bigint',
-  numeric: 'numeric',
-  timestamptz: 'timestamptz',
-  date: 'date',
-  jsonb: 'jsonb',
-};
-
-function sqlType(kind: string): string {
-  return SQL_TYPES[kind] ?? kind;
-}
-
 function columnClause(column: ColumnDescriptionLike): string {
   // The generation clause sits directly after the type, and `generatedClause` refuses the pairs
   // Postgres has no column for. Every other part below is unchanged and unreachable for a
@@ -160,15 +143,19 @@ function retypeColumn(
   recorded: ColumnDescription,
   plan: Plan,
   moved: MovedAside,
+  retyped: ReadonlySet<string>,
 ): Regeneration {
   const wanted = sqlType(column.kind);
   const table = live.name;
   // A generated column moves by its own rules — see `generated-column.ts`. Asked whenever EITHER
   // side is one, because becoming generated and ceasing to be are both changes with a statement.
   if (isGenerated(column) || recorded.generated !== undefined) {
-    return regenerate(table, column, wanted, recorded, plan);
+    return regenerate(live, column, wanted, recorded, plan, moved);
   }
-  if (recorded.dataType === wanted) return 'unchanged';
+  // The set, never `recorded.dataType === wanted` a second time: `retypedColumns` decided this for
+  // the whole schema before any statement was written, because the foreign keys a retype breaks
+  // are recorded on tables this diff is not looking at (`retype-keys.ts`).
+  if (!retyped.has(column.column)) return 'unchanged';
   moveDependentsAside(live, column.column, plan, moved);
   const alter = (type: string): string =>
     `alter table ${identifier(table).text} alter column ${identifier(column.column).text} ` +
@@ -178,7 +165,12 @@ function retypeColumn(
   return 'altered';
 }
 
-function diffTable(entity: EntityDescriptionLike, live: TableDescription, plan: Plan): void {
+function diffTable(
+  entity: EntityDescriptionLike,
+  live: TableDescription,
+  plan: Plan,
+  retyped: ReadonlySet<string>,
+): void {
   const existing = new Map(live.columns.map((column) => [column.name, column]));
   const added = new Set<string>();
   // A column `regenerate` had to replace outright: `add column` implies no index, so every index
@@ -189,7 +181,7 @@ function diffTable(entity: EntityDescriptionLike, live: TableDescription, plan:
   for (const column of entity.columns) {
     const recorded = existing.get(column.column);
     if (recorded !== undefined) {
-      if (retypeColumn(live, column, recorded, plan, moved) === 'rebuilt') {
+      if (retypeColumn(live, column, recorded, plan, moved, retyped) === 'rebuilt') {
         rebuilt.add(column.column);
       }
       continue;
@@ -216,23 +208,9 @@ function diffTable(entity: EntityDescriptionLike, live: TableDescription, plan:
     );
   }
 
-  const indexed = new Map(live.indexes.map((index) => [index.name, index]));
-  for (const index of declaredIndexes(entity)) {
-    const recorded = indexed.get(index.name);
-    // A rebuilt column took its indexes down with it, and a retype dropped the ones whose
-    // predicate it could not survive — either way this one is CREATED rather than compared:
-    // `redefineIndex` sees a definition that never moved and would emit nothing at all.
-    const gone = moved.indexes.has(index.name) || index.columns.some((each) => rebuilt.has(each));
-    if (recorded !== undefined && !gone) {
-      redefineIndex(entity.table, index, recorded, plan);
-      continue;
-    }
-    // `added` only: an index over a column that was already there is implied by no clause this
-    // migration emits, so it still needs a statement of its own.
-    if (impliedByColumnClause(entity, index, added)) continue;
-    plan.up.push(createIndex(entity.table, index));
-    plan.down.push(dropIndex(index.name));
-  }
+  // Both directions, in `index-plan.ts`: a recorded index the entity no longer declares is DROPPED
+  // there, which is the arm this loop did not have for as long as it lived here.
+  indexPlan(entity, live, plan, { added, rebuilt, moved: moved.indexes });
 
   // Last: a CHECK may read a column this migration just added, and `add constraint` on a column
   // that does not exist yet is `42703`. `check-ddl.ts` owns which of them move; `rebuilt` because a
@@ -292,12 +270,20 @@ export function generateMigration(options: GenerateOptions): GeneratedMigration
   // 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: [] };
+  // Ahead of EVERYTHING, and at the far end of `down`: a foreign key compiled against a column
+  // being retyped has to be gone before the first ALTER and back after the last one, and both ends
+  // of one key can move in two different entities' diffs (`retype-keys.ts`).
+  const preAlters: 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 };
+  // Before the loop, because the answer spans it: `diffTable` is handed one entity's recorded row
+  // and the key that a retype of its column breaks is recorded on whichever table OWNS the key.
+  const retyped = retypedColumns(options.entities, current);
+  const predropped = moveKeysAside(current, retyped, doomed, preAlters);
+  const plans: ConstraintPlans = { constraints, preDrops, doomed, predropped };
 
   for (const entity of options.entities) {
     const live = findTable(current, entity.table);
@@ -307,7 +293,7 @@ export function generateMigration(options: GenerateOptions): GeneratedMigration
       plan.down.push(`drop table ${identifier(entity.table).text};`);
       continue;
     }
-    diffTable(entity, live, plan);
+    diffTable(entity, live, plan, retypedIn(retyped, entity.table));
     const kept = new Set(entity.columns.map((column) => column.column));
     for (const column of live.columns) {
       if (kept.has(column.name)) continue;
@@ -365,15 +351,17 @@ export function generateMigration(options: GenerateOptions): GeneratedMigration
   // `current`, not the entities alone: an `assert` whose CHECK a previous migration recorded is a
   // loss only because THIS plan drops it, and the recorded schema is the only thing that knows.
   const unrendered = unrenderedOf(options.entities, current);
-  const body = plan.up.join('\n');
+  const body = [...preAlters.up, ...plan.up].join('\n');
   const up = body.length === 0 ? body : unrenderedComment(unrendered) + body;
   return {
     id,
     name: options.name,
     fileName: `migrations/${id}.sql`,
     up,
-    // Reverse order: the last thing created is the first thing dropped.
-    down: [...plan.down].reverse().join('\n'),
+    // Reverse order: the last thing created is the first thing dropped. `preAlters` goes in at the
+    // FRONT here precisely so reversal puts it last — a key is added back only once both of its
+    // ends have been retyped back, which is every other statement in the script.
+    down: [...preAlters.down, ...plan.down].reverse().join('\n'),
     snapshot: snapshotOf(options.entities),
     destructive: isDestructive(up),
     unrendered,