@ultimat3/db 14.0.0 → 16.0.0

package/src/generate.ts

@@ -3,52 +3,32 @@
 // the CLI passes `describeEntities()` and the types below mirror `EntityDescription` field for
 // field. Every generated migration must be reversible; a drop that loses data refuses instead.
 
-import { assert, systemClock } from '@ultimat3/core';
+import { systemClock } from '@ultimat3/core';
 import { checkClauses, checkPlan, declaredChecks } from './check-ddl';
 import { defaultExpression } from './column-default';
 import { isDestructive } from './destructive';
 import { dropOrder } from './drop-order';
-import type {
-  ColumnDescriptionLike,
-  EntityDescriptionLike,
-  IndexDescriptionLike,
-} from './entity-shape';
-import { migrationIrreversible } from './errors';
+import type { ColumnDescriptionLike, EntityDescriptionLike } from './entity-shape';
 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 { declaredMethod, indexMethodOf, indexMethodSql } from './index-method';
+import { createIndex, impliedByColumnClause } from './index-ddl';
+import { indexPlan } from './index-plan';
 import {
   type ColumnDescription,
   findTable,
-  type IndexDescription,
   type SchemaDescription,
   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
@@ -74,34 +54,6 @@ function columnClause(column: ColumnDescriptionLike): string {
   return parts.join(' ');
 }
 
-/**
- * A `unique` column clause already creates an index, and Postgres names it exactly what the
- * entity's own convention names it — `<table>_<column>_key`. Emitting `create unique index` for
- * it too is the same index twice: `42P07`, and a migration that cannot be applied at all.
- * Mirrors the rule `entity()` already applies to a foreign key indexing its own column.
- *
- * A **partial** unique index is not that index: the column clause constrains every row, so
- * skipping the partial one would silently widen the constraint the entity declared.
- */
-function impliedByColumnClause(
-  entity: EntityDescriptionLike,
-  index: IndexDescriptionLike,
-  added: ReadonlySet<string>,
-): boolean {
-  const [only] = index.columns;
-  if (!index.unique || index.where !== null || index.columns.length !== 1 || only === undefined) {
-    return false;
-  }
-  const column = entity.columns.find((each) => each.column === only);
-  // `columnClause` writes `unique` under exactly this condition — keep the two in step.
-  //
-  // NOT an optional chain, despite what biome's useOptionalChain suggests: `column?.unique` is
-  // `boolean | undefined`, and this function returns `boolean`. The lint rule marks its own fix
-  // unsafe for exactly this reason — applying it turned a green typecheck red.
-  // biome-ignore lint/complexity/useOptionalChain: an optional chain widens the return to include undefined
-  return column !== undefined && column.unique && !column.primaryKey && added.has(only);
-}
-
 export function snapshotOf(entities: readonly EntityDescriptionLike[]): SchemaDescription {
   const tables = [...entities]
     .sort((a, b) => (a.table < b.table ? -1 : 1))
@@ -172,68 +124,39 @@ function createTable(entity: EntityDescriptionLike): readonly string[] {
   return statements;
 }
 
-/**
- * Every part of the declaration reaches the statement: the whole column list in its declared
- * order, the direction when one was asked for, and the predicate that makes it partial. A part
- * dropped here is a constraint the database does not hold or an index the planner cannot use.
- */
-function createIndex(table: string, index: IndexDescriptionLike): string {
-  assert(
-    index.columns.length > 0,
-    `index "${index.name}" on "${table}" names no columns`,
-    `indexes: [{ on: ['<column>'] }]   # name the columns in the entity(), then x db gen`,
-  );
-  const method = index.using ?? 'btree';
-  // Two rules Postgres has and a declaration can break, refused here rather than at migrate time:
-  // GIN supports neither a unique index nor an ASC/DESC option, and either one reaches the server
-  // as a syntax error inside `ROLE=migrate` — a release phase that fails with the server's words
-  // and none of the entity's. `X_INVARIANT` for the reason `createIndex` already uses it on an
-  // index naming no columns: a declaration this build cannot honour is refused, never reinterpreted.
-  assert(
-    method === 'btree' || !index.unique,
-    `index "${index.name}" on "${table}" is unique and ${method}; Postgres has no unique ${method} index`,
-    `indexes: [{ on: ['<column>'], using: '${method}' }]   # drop unique, or drop using`,
-  );
-  assert(
-    method === 'btree' || index.order === null,
-    `index "${index.name}" on "${table}" is ${method} and ${index.order}; only a btree orders its keys`,
-    `indexes: [{ on: ['<column>'], using: '${method}' }]   # drop order, or drop using`,
-  );
-  const kind = index.unique ? 'create unique index' : 'create index';
-  const direction = index.order === null ? '' : ` ${index.order}`;
-  const columns = index.columns
-    .map((column) => `${identifier(column).text}${direction}`)
-    .join(', ');
-  const predicate = index.where === null ? '' : ` where (${index.where})`;
-  // Re-derived from the closed set, never spliced: `indexMethodSql` answers `''` for a btree, so
-  // an index that declared no method emits the statement this generator always emitted, byte for
-  // byte, and one that declared a method Postgres does not have is refused instead of built.
-  return (
-    `${kind} ${identifier(index.name).text} on ${identifier(table).text}` +
-    `${indexMethodSql(method)} (${columns})${predicate};`
-  );
-}
-
 /**
  * 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
  * snapshot this run records claims `char(3)` — two claims with no statement between them. Both
  * sides are generated spellings (`current` is a previous migration's own snapshot), so any
  * difference is a real kind change, not a catalog alias.
+ *
+ * The ALTER is not the whole statement list: Postgres compiled every predicate written against
+ * this column with its OLD type and cannot recompile one, so a partial index or a CHECK that reads
+ * it is dropped FIRST and `moved` carries the names on to the arms that would otherwise act on
+ * them. Without that the retype is `42883` and the migration aborts mid-run
+ * (`retype-dependents.ts`).
  */
 function retypeColumn(
-  table: string,
+  live: TableDescription,
   column: ColumnDescriptionLike,
   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} ` +
     `type ${type} using ${identifier(column.column).text}::${type};`;
@@ -242,64 +165,23 @@ function retypeColumn(
   return 'altered';
 }
 
-/** The parts of an index Postgres cannot alter in place — every one of them is a rebuild. */
-function indexShape(index: IndexDescriptionLike | IndexDescription): string {
-  return JSON.stringify([
-    [...index.columns],
-    index.unique,
-    index.where,
-    index.order ?? null,
-    indexMethodOf(index),
-  ]);
-}
-
-/**
- * A same-named index whose definition moved is dropped and recreated, because Postgres has no
- * `alter index` for any of it — the column list, the uniqueness, the predicate and the direction
- * are all fixed at creation.
- *
- * Matching on the name alone was the gap: `where` and `order` were not even recorded, so an
- * entity narrowing an index to a predicate, or reversing it to `desc`, generated an empty
- * migration and the database kept serving the old one. Both sides here are *generated* spellings
- * — `recorded` is a previous migration's own snapshot, never the catalog's rewriting of it — so a
- * text difference in `where` is a real change and not a formatting one.
- */
-function redefineIndex(
-  table: string,
-  index: IndexDescriptionLike,
-  recorded: IndexDescription,
+function diffTable(
+  entity: EntityDescriptionLike,
+  live: TableDescription,
   plan: Plan,
+  retyped: ReadonlySet<string>,
 ): void {
-  if (indexShape(index) === indexShape(recorded)) return;
-  plan.up.push(`drop index ${identifier(index.name).text};`, createIndex(table, index));
-  // `down` is reversed at assembly, so the pair is pushed forwards and read backwards: recreating
-  // the recorded definition is what must land last, after the new one is dropped.
-  plan.down.push(
-    createIndex(table, {
-      name: recorded.name,
-      columns: recorded.columns,
-      unique: recorded.unique,
-      where: recorded.where,
-      order: recorded.order,
-      // `declaredMethod`, never a cast: `recorded` is a snapshot's, typed open because the catalog
-      // shares the shape, and a method this generator cannot emit must refuse rather than be
-      // rebuilt as a btree — a `down` that recreates the wrong structure is worse than none.
-      ...(recorded.using === undefined ? {} : { using: declaredMethod(recorded.using) }),
-    }),
-    `drop index ${identifier(index.name).text};`,
-  );
-}
-
-function diffTable(entity: EntityDescriptionLike, live: TableDescription, plan: Plan): 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
   // over it has to be stated again even though its own definition never moved.
   const rebuilt = new Set<string>();
+  // What a retype dropped ahead of itself, read by the two arms below.
+  const moved: MovedAside = { indexes: new Set(), checks: new Set() };
   for (const column of entity.columns) {
     const recorded = existing.get(column.column);
     if (recorded !== undefined) {
-      if (retypeColumn(entity.table, column, recorded, plan) === 'rebuilt') {
+      if (retypeColumn(live, column, recorded, plan, moved, retyped) === 'rebuilt') {
         rebuilt.add(column.column);
       }
       continue;
@@ -326,26 +208,15 @@ 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, so this one is CREATED rather than compared:
-    // `redefineIndex` sees a definition that never moved and would emit nothing at all.
-    if (recorded !== undefined && !index.columns.some((column) => rebuilt.has(column))) {
-      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(`drop index ${identifier(index.name).text};`);
-  }
+  // 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
-  // column dropped and re-added lost its constraint while the snapshot still records it.
-  checkPlan(entity, live, plan, rebuilt);
+  // column dropped and re-added lost its constraint while the snapshot still records it, and
+  // `moved.checks` because a retype already dropped the ones written against the old type.
+  checkPlan(entity, live, plan, rebuilt, moved.checks);
 }
 
 export interface GenerateOptions {
@@ -399,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);
@@ -414,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;
@@ -472,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,

package/src/generated-column.ts

@@ -6,7 +6,9 @@
 import { assert } from '@ultimat3/core';
 import type { ColumnDescriptionLike } from './entity-shape';
 import type { Plan } from './foreign-key-plan';
-import type { ColumnDescription } from './introspect';
+import type { ColumnDescription, TableDescription } from './introspect';
+import type { MovedAside } from './retype-dependents';
+import { moveDependentsAside } from './retype-dependents';
 import { identifier } from './sql';
 
 /** How a column that moved was brought back into line — what the caller has to do next, if anything. */
@@ -68,14 +70,26 @@ export const isGenerated = (column: ColumnDescriptionLike): boolean =>
  * plain → generated (there is no `set expression` for a column that has none) and a column whose
  * recorded expression is unknown. `drop expression` is the one that HAS a statement, and it is the
  * generated → plain direction, which keeps the values it computed.
+ *
+ * **The rebuild moves the column's dependents aside first, and it is `retype-dependents.ts` that
+ * says which — never a second answer written here.** The `rebuilt`
+ * set `diffTable` carries into its index loop is keyed on an index's COLUMNS, so a partial index
+ * whose `where` names this column and whose key columns do not was dropped with the column by
+ * `drop column` and re-created by nothing: measured, the table came back with the index gone, the
+ * snapshot still recording it, and `down` unable to restore it. An invariant's CHECK reading the
+ * column is the same loss one arm over. `moveDependentsAside` drops each of them explicitly,
+ * restores them in `down`, and puts the name in `moved` — which is what makes the ordinary diff
+ * CREATE the declared one instead of comparing a definition that never moved.
  */
 export function regenerate(
-  table: string,
+  live: TableDescription,
   column: ColumnDescriptionLike,
   wantedType: string,
   recorded: ColumnDescription,
   plan: Plan,
+  moved: MovedAside,
 ): Regeneration {
+  const table = live.name;
   const wanted = column.generated ?? null;
   const held = recorded.generated ?? null;
   if (wanted === null && held === null) return 'unchanged';
@@ -89,6 +103,7 @@ export function regenerate(
   // column again. Reported as `rebuilt` so the caller can put the indexes back — an `add column`
   // implies none of them.
   if (held === null) {
+    moveDependentsAside(live, column.column, plan, moved);
     const dropColumn = `alter table ${identifier(table).text} drop column ${identifier(column.column).text};`;
     plan.up.push(
       dropColumn,
@@ -104,16 +119,26 @@ export function regenerate(
     );
     return 'rebuilt';
   }
-  let moved = false;
+  let changed = false;
+  // NOT `moveDependentsAside`, and the reason is measured rather than assumed. This ALTER trips the
+  // same `42883` (`operator does not exist: text > integer`, on a generated `integer` column under
+  // `where (doubled > 0)`) — but moving the index aside only relocates the failure to the
+  // `create index` that puts it back, because a predicate whose operator the NEW type has no
+  // resolution for cannot be written either. The plain path's dependents survive precisely because
+  // an untyped literal re-resolves (`status = 'published'` under an enum and under `text`), and a
+  // generated column reaching that shape needs its EXPRESSION changed in the same migration, which
+  // `regenerate` emits AFTER this statement. Left open deliberately, with the failure named.
   if (recorded.dataType !== wantedType) {
     plan.up.push(`${alterColumn(table, column.column)} type ${wantedType};`);
     plan.down.push(`${alterColumn(table, column.column)} type ${recorded.dataType};`);
-    moved = true;
+    changed = true;
   }
+  // Nothing moves for this one either, and here it is free: `set expression` recomputes every value
+  // and leaves the type alone, so nothing compiled against the type has anything to recompile.
   if (held !== wanted) {
     plan.up.push(`${alterColumn(table, column.column)} set expression as (${wanted});`);
     plan.down.push(`${alterColumn(table, column.column)} set expression as (${held});`);
-    moved = true;
+    changed = true;
   }
-  return moved ? 'altered' : 'unchanged';
+  return changed ? 'altered' : 'unchanged';
 }

package/src/index-ddl.ts

@@ -0,0 +1,188 @@
+// Single responsibility: the DDL an entity's INDEX declaration becomes — the `create index` a
+// declaration writes out, what makes two definitions the same index, and what a moved definition
+// rebuilds. Split out of `generate.ts` at the 500-line ceiling, along the seam `check-ddl.ts` and
+// `generated-column.ts` already drew: `generate.ts` assembles a plan, this file writes the index
+// statements it puts in it, and `invariant-ddl.ts` decides which indexes a table declares.
+
+import { assert } from '@ultimat3/core';
+import type { EntityDescriptionLike, IndexDescriptionLike } from './entity-shape';
+import type { Plan } from './foreign-key-plan';
+import { declaredMethod, indexMethodOf, indexMethodSql } from './index-method';
+import type { IndexDescription } from './introspect';
+import { identifier } from './sql';
+
+/**
+ * A `unique` column clause already creates an index, and Postgres names it exactly what the
+ * entity's own convention names it — `<table>_<column>_key`. Emitting `create unique index` for
+ * it too is the same index twice: `42P07`, and a migration that cannot be applied at all.
+ * Mirrors the rule `entity()` already applies to a foreign key indexing its own column.
+ *
+ * A **partial** unique index is not that index: the column clause constrains every row, so
+ * skipping the partial one would silently widen the constraint the entity declared.
+ */
+export function impliedByColumnClause(
+  entity: EntityDescriptionLike,
+  index: IndexDescriptionLike,
+  added: ReadonlySet<string>,
+): boolean {
+  const [only] = index.columns;
+  if (!index.unique || index.where !== null || index.columns.length !== 1 || only === undefined) {
+    return false;
+  }
+  const column = entity.columns.find((each) => each.column === only);
+  // `columnClause` writes `unique` under exactly this condition — keep the two in step.
+  //
+  // NOT an optional chain, despite what biome's useOptionalChain suggests: `column?.unique` is
+  // `boolean | undefined`, and this function returns `boolean`. The lint rule marks its own fix
+  // unsafe for exactly this reason — applying it turned a green typecheck red.
+  // biome-ignore lint/complexity/useOptionalChain: an optional chain widens the return to include undefined
+  return column !== undefined && column.unique && !column.primaryKey && added.has(only);
+}
+
+/**
+ * Every part of the declaration reaches the statement: the whole column list in its declared
+ * order, the direction when one was asked for, and the predicate that makes it partial. A part
+ * dropped here is a constraint the database does not hold or an index the planner cannot use.
+ */
+export function createIndex(table: string, index: IndexDescriptionLike): string {
+  assert(
+    index.columns.length > 0,
+    `index "${index.name}" on "${table}" names no columns`,
+    `indexes: [{ on: ['<column>'] }]   # name the columns in the entity(), then x db gen`,
+  );
+  const method = index.using ?? 'btree';
+  // Two rules Postgres has and a declaration can break, refused here rather than at migrate time:
+  // GIN supports neither a unique index nor an ASC/DESC option, and either one reaches the server
+  // as a syntax error inside `ROLE=migrate` — a release phase that fails with the server's words
+  // and none of the entity's. `X_INVARIANT` for the reason `createIndex` already uses it on an
+  // index naming no columns: a declaration this build cannot honour is refused, never reinterpreted.
+  assert(
+    method === 'btree' || !index.unique,
+    `index "${index.name}" on "${table}" is unique and ${method}; Postgres has no unique ${method} index`,
+    `indexes: [{ on: ['<column>'], using: '${method}' }]   # drop unique, or drop using`,
+  );
+  assert(
+    method === 'btree' || index.order === null,
+    `index "${index.name}" on "${table}" is ${method} and ${index.order}; only a btree orders its keys`,
+    `indexes: [{ on: ['<column>'], using: '${method}' }]   # drop order, or drop using`,
+  );
+  const kind = index.unique ? 'create unique index' : 'create index';
+  const direction = index.order === null ? '' : ` ${index.order}`;
+  const columns = index.columns
+    .map((column) => `${identifier(column).text}${direction}`)
+    .join(', ');
+  const predicate = index.where === null ? '' : ` where (${index.where})`;
+  // Re-derived from the closed set, never spliced: `indexMethodSql` answers `''` for a btree, so
+  // an index that declared no method emits the statement this generator always emitted, byte for
+  // byte, and one that declared a method Postgres does not have is refused instead of built.
+  return (
+    `${kind} ${identifier(index.name).text} on ${identifier(table).text}` +
+    `${indexMethodSql(method)} (${columns})${predicate};`
+  );
+}
+
+/** `drop index "n";` — the one spelling, so a drop and its recreate cannot name it differently. */
+export const dropIndex = (name: string): string => `drop index ${identifier(name).text};`;
+
+/**
+ * Whether Postgres could be backing this RECORDED index with a UNIQUE constraint rather than
+ * holding it as an index of its own — which decides the only question `dropIndex` cannot answer.
+ *
+ * A UNIQUE constraint's index is unique, total, unordered and btree; `add constraint … unique`
+ * and a `unique` column clause can produce nothing else. So an index missing any one of those is
+ * provably an index, and `drop index` on it is right. Everything else is genuinely ambiguous —
+ * see `dropRecordedIndex`.
+ */
+export function mayBeConstraintBacked(index: IndexDescription): boolean {
+  return (
+    index.unique &&
+    !index.primary &&
+    index.where === null &&
+    index.order === null &&
+    indexMethodOf(index) === 'btree'
+  );
+}
+
+/**
+ * Remove a RECORDED index whose kind this generator cannot know, in statements that are correct
+ * on both databases it cannot tell apart.
+ *
+ * `TableDescription` carries no discriminator, and it cannot be given one that would help: the
+ * SAME declaration reaches the server as a CONSTRAINT or as an INDEX depending on which migration
+ * created it. A `unique` column on a table `createTable` writes emits `create table … slug text
+ * unique`, and Postgres backs that with a constraint named `posts_slug_key`; the same column
+ * gaining `unique` later takes `diffTable`'s `create unique index "posts_slug_key"` and is a plain
+ * index. `snapshotOf` records both as `{ unique: true, primary: false }`, and every sidecar already
+ * on disk was written that way — a new field could not classify one of them retroactively.
+ *
+ * Measured on 18.4 (`index-removal.live.test.ts`), which is why the pair and not a guess:
+ *
+ * | statement                                  | on a constraint's index | on a plain index |
+ * |--------------------------------------------|-------------------------|------------------|
+ * | `drop index "n"`                           | **2BP01**               | ok               |
+ * | `drop index if exists "n"`                 | **2BP01** — not suppressed | ok            |
+ * | `alter table … drop constraint if exists`  | drops it, index and all | notice, no-op    |
+ *
+ * Constraint first, then the index: reversed, the `drop index` reaches a constraint's index and is
+ * the 2BP01 this exists to avoid. Both halves carry `if exists`, so whichever one did nothing says
+ * so with a notice rather than 42704.
+ */
+export function dropRecordedIndex(table: string, index: IndexDescription): readonly string[] {
+  if (!mayBeConstraintBacked(index)) return [dropIndex(index.name)];
+  return [
+    `alter table ${identifier(table).text} drop constraint if exists ${identifier(index.name).text};`,
+    `drop index if exists ${identifier(index.name).text};`,
+  ];
+}
+
+/**
+ * A RECORDED index as a declaration this generator can emit again — `declaredMethod`, never a
+ * cast: the recorded side is typed open because the catalog shares the shape, and a method this
+ * generator cannot write must refuse rather than be rebuilt as a btree. One copy, because
+ * `redefineIndex`'s `down` and `retype-dependents.ts`'s restore ask the same question.
+ */
+export function asDeclared(index: IndexDescription): IndexDescriptionLike {
+  return {
+    name: index.name,
+    columns: index.columns,
+    unique: index.unique,
+    where: index.where,
+    order: index.order,
+    ...(index.using === undefined ? {} : { using: declaredMethod(index.using) }),
+  };
+}
+
+/** The parts of an index Postgres cannot alter in place — every one of them is a rebuild. */
+export function indexShape(index: IndexDescriptionLike | IndexDescription): string {
+  return JSON.stringify([
+    [...index.columns],
+    index.unique,
+    index.where,
+    index.order ?? null,
+    indexMethodOf(index),
+  ]);
+}
+
+/**
+ * A same-named index whose definition moved is dropped and recreated, because Postgres has no
+ * `alter index` for any of it — the column list, the uniqueness, the predicate and the direction
+ * are all fixed at creation.
+ *
+ * Matching on the name alone was the gap: `where` and `order` were not even recorded, so an
+ * entity narrowing an index to a predicate, or reversing it to `desc`, generated an empty
+ * migration and the database kept serving the old one. Both sides here are *generated* spellings
+ * — `recorded` is a previous migration's own snapshot, never the catalog's rewriting of it — so a
+ * text difference in `where` is a real change and not a formatting one.
+ */
+export function redefineIndex(
+  table: string,
+  index: IndexDescriptionLike,
+  recorded: IndexDescription,
+  plan: Plan,
+): void {
+  if (indexShape(index) === indexShape(recorded)) return;
+  plan.up.push(dropIndex(index.name), createIndex(table, index));
+  // `down` is reversed at assembly, so the pair is pushed forwards and read backwards: recreating
+  // the recorded definition is what must land last, after the new one is dropped.
+  plan.down.push(createIndex(table, asDeclared(recorded)), dropIndex(index.name));
+}