@intentius/chant-lexicon-sql 0.124.46 → 0.124.48

package/src/postgres/migrate/observe.ts

@@ -24,12 +24,13 @@
  * - `done`: the server holds the declared column and nothing of the
  *   migration is left.
  *
+ * A partitioned table's indexes are carried over per partition (`./steps.ts`).
  * Anything else is refused with a {@link MigrationRefusal}, naming what to
  * do: a table that is not there, a partition (run it on the partitioned
  * table) or an inheritance tree; no primary key to batch by; a column in the
  * partition key; a generated column; a column change the Op does not make
- * (a rename and a type change at once, a rename of a column with a default
- * or a sequence); something that uses the column and is
+ * (a rename and a type change without `reverse`, a rename of a column with a
+ * default or a sequence without `defaultAtContract`); something that uses the column and is
  * not carried over to the new one (`./carry.ts`: indexes, key, check and
  * foreign key constraints and declared views are); a publication that sends
  * it; a working object chant did not make.
@@ -50,7 +51,7 @@ import type { DeclaredPgObject } from "../apply/statements";
 import { col, migrationNames, MIGRATION_TRAILER_KEY, pgName, type MigrationChange, type MigrationNames } from "./names";
 import { publicationsOf, type PublicationHit } from "./replication";
 import { keyText, type KeyColumn } from "./batches";
-import { carriedStates, carriedSubject, discoverDependents, replaceColumn, storedType, type CarriedObject, type CarriedState, type CarriedView, type ColumnSequence, type Dependents } from "./carry";
+import { carriedStates, carriedSubject, columnSequence, discoverDependents, replaceColumn, storedType, type CarriedObject, type CarriedState, type CarriedView, type ColumnSequence, type Dependents } from "./carry";
 
 /** A refusal: the migration cannot start, or cannot go on, for a reason a person has to act on. */
 export class MigrationRefusal extends Error {
@@ -102,7 +103,7 @@ export interface MigrationObservation {
   carriedStates: Map<string, CarriedState>;
   /** The views that read the old column, made again at the switch. */
   views: CarriedView[];
-  /** The sequence that gives the old column its values (identity or serial), moved to the new column at the switch. */
+  /** The sequence that gives the old column its values (identity or serial): moved to the new column at the switch for a type change, at the contract for a rename. */
   sequence?: ColumnSequence;
   /** The table is partitioned: every step runs on it, and its partitions follow. */
   partitioned: boolean;
@@ -118,6 +119,10 @@ export interface MigrationObservation {
   changes: PgChange[];
   /** The expression the new column's value is computed with, over the old row's columns. */
   expression: string;
+  /** A rename with a type change: the expression over the new row's columns that gives the old column's value. */
+  reverse?: string;
+  /** A rename keeps its default, serial or identity on the old column until the contract (`defaultAtContract`). */
+  defaultAtContract?: boolean;
   publications: PublicationHit[];
   major: number;
 }
@@ -132,6 +137,10 @@ export interface ObserveInput {
   objects?: readonly DeclaredPgObject[];
   /** The type change's expression, over the old row's columns. Default: `CAST(<column> AS <declared type>)`. */
   using?: string;
+  /** A rename with a type change: the expression over the new row's columns that gives the old column's value. */
+  reverse?: string;
+  /** A rename of a column with a default, serial or identity: the declared default lands on the new column at the contract, not the switch. */
+  defaultAtContract?: boolean;
   /** The major the build targets; the server's own wins. */
   major?: number;
 }
@@ -216,7 +225,7 @@ async function columnChanges(input: ObserveInput): Promise<{ changes: PgChange[]
 
 const ruleText = (c: PgChange) => `${c.rule} ${PG_CLASSIFIER_RULES[c.rule].title} (${c.field}${c.before !== undefined || c.after !== undefined ? `: ${c.before ?? "-"} -> ${c.after ?? "-"}` : ""})`;
 
-interface RelationRow {
+export interface RelationRow {
   oid: string;
   kind: string;
   partition: boolean;
@@ -371,7 +380,8 @@ export async function observeMigration(input: ObserveInput): Promise<MigrationOb
         );
       },
     );
-    if (change === "type") {
+    const retyped = change === "rename" && input.reverse !== undefined;
+    if (change === "type" || retyped) {
       expression = input.using ?? `CAST(${col(sourceName)} AS ${storedType(column.type)})`;
       if (expression.includes("$chant$")) throw new MigrationRefusal(`${where}: the using expression may not contain $chant$, which quotes the dual-write function's body`);
     } else if (input.using !== undefined) {
@@ -379,7 +389,7 @@ export async function observeMigration(input: ObserveInput): Promise<MigrationOb
     }
     // The declared type as the classifier compared it: the server's spelling (character varying(10), not varchar(10)).
     const serial = storedType(column.type) !== column.type;
-    const expectedType = change === "type" ? (serial ? storedType(column.type)! : String(typeChange?.after ?? column.type)) : source.type;
+    const expectedType = change === "type" || retyped ? (serial ? storedType(column.type)! : String(typeChange?.after ?? column.type)) : source.type;
     if (newColumn && newColumn.type !== expectedType) {
       throw new MigrationRefusal(
         `${where}: ${newColumn.name} was made as ${newColumn.type}, from another declaration of ${input.column} (now ${column.type}). The run fails so onFailure drops it, and the next run starts again from the current declaration.`,
@@ -397,6 +407,12 @@ export async function observeMigration(input: ObserveInput): Promise<MigrationOb
     }
   }
 
+  // After a rename's switch the old column still holds the default or the identity the contract moves, and its sequence is read for it.
+  if (state === "switched" && old && (old.identity || old.default?.includes("nextval("))) {
+    const seq = await columnSequence(client, rel.oid, old.attnum);
+    if (seq) dependents = { ...dependents, sequence: seq };
+  }
+
   return {
     state,
     names,
@@ -419,13 +435,15 @@ export async function observeMigration(input: ObserveInput): Promise<MigrationOb
     ...(check ? { check } : {}),
     changes,
     expression,
+    ...(input.reverse !== undefined && state === "migrate" ? { reverse: input.reverse } : {}),
+    ...(input.defaultAtContract && state === "migrate" ? { defaultAtContract: true } : {}),
     publications,
     major,
   };
 }
 
 /** The checks that hold only while there is something to migrate. Returns the batch key and what the Op carries over. */
-async function refuseUnsupported(
+export async function refuseUnsupported(
   input: ObserveInput,
   names: MigrationNames,
   rel: RelationRow,
@@ -437,20 +455,38 @@ async function refuseUnsupported(
 ): Promise<{ batchKey: string; keyColumns: KeyColumn[]; dependents: Pick<Dependents, "carried" | "views" | "sequence"> }> {
   const where = `${names.schema}.${names.table}`;
   const oid = rel.oid;
-  if (rename && typeChange) {
+  if (rename && typeChange && input.reverse === undefined) {
     throw new MigrationRefusal(
       `${where}: ${source.name} is renamed to ${names.column} and its type changes (${typeChange.before} -> ${typeChange.after}) in one declaration. ` +
-        `Migrate one at a time: declare the rename with the old type, run the Op to its end, then change the type. ` +
-        `(In one run both names would stay written until the contract, which needs a conversion back to the old type for writers of the new name; chant #3331.)`,
+        `Both names stay written until the contract, so a writer of the new name needs its value converted back to the old type: give that expression as reverse ` +
+        `(over the row's columns, the new column by its declared name; using gives the new value from the old one). The verification fails the run unless reverse over every new value gives the old one back. ` +
+        `Or migrate one at a time: declare the rename with the old type, run the Op to its end, then change the type.`,
+    );
+  }
+  if (input.reverse !== undefined && !(rename && typeChange)) {
+    throw new MigrationRefusal(`${where}.${names.column}: reverse is for a rename combined with a type change, and this migration is ${rename ? "a rename only" : "a type change without a rename"}`);
+  }
+  if (input.reverse !== undefined && input.reverse.includes("$chant$")) {
+    throw new MigrationRefusal(`${where}: the reverse expression may not contain $chant$, which quotes the dual-write function's body`);
+  }
+  const hasDefault = source.default !== undefined || column.default !== undefined;
+  if (rename && typeChange && (hasDefault || source.identity || column.generated?.kind === "identity")) {
+    throw new MigrationRefusal(
+      `${where}: ${source.name} has a default, serial or identity, and its rename also changes its type. The default is an expression of the old type; converting it, and the sequence's type, ` +
+        `is a third conversion on top of using and reverse that nothing verifies. Rename first (defaultAtContract: true), run the Op to its end, then change the type.`,
     );
   }
-  if (rename && (source.default !== undefined || column.default !== undefined)) {
+  if (rename && (hasDefault || source.identity) && !input.defaultAtContract) {
     throw new MigrationRefusal(
-      `${where}: ${source.name} has a default (${source.default ?? column.default}). During a rename both columns are written, each from the other, ` +
+      `${where}: ${source.name} has a default (${source.default ?? column.default ?? "identity"}). During a rename both columns are written, each from the other, ` +
         `and a row inserted by a writer that names one column would get the other's default, which the trigger cannot tell from a value it was given. ` +
-        `Drop the default first (the applier does), rename, then declare it again. A rename that keeps its default needs versioned views (chant #3331).`,
+        `Set defaultAtContract: true to leave the new column without the default until the contract, which gives the default to the new column in the contract's transaction; ` +
+        `until then an INSERT that names the new column with an explicit NULL gets the default, and UPDATE ... SET <new> = DEFAULT sets NULL. Or drop the default first (the applier does), rename, then declare it again.`,
     );
   }
+  if (input.defaultAtContract && !(rename && (hasDefault || source.identity))) {
+    throw new MigrationRefusal(`${where}.${names.column}: defaultAtContract is for a rename of a column with a default, serial or identity, and this migration is not one`);
+  }
   if (source.generated || (column.generated && column.generated.kind !== "identity")) {
     throw new MigrationRefusal(
       `${where}.${source.name} is a generated column. There is no expand and contract for one: Postgres cannot make an existing column generated, so the new column could only be added generated, ` +
@@ -475,6 +511,7 @@ async function refuseUnsupported(
     declared: input.declared,
     defaultSchema: input.target.defaultSchema,
     partitioned: rel.kind === "p",
+    ...(input.defaultAtContract ? { keepSequence: true } : {}),
   });
   if (dependents.refused.length > 0) {
     throw new MigrationRefusal(
@@ -510,6 +547,8 @@ export function migrationPlanSubject(o: MigrationObservation): Record<string, un
     from: o.source ? { name: o.source.name, type: o.source.type, notNull: o.source.notNull, default: o.source.default ?? null } : null,
     to: { name: o.column.name, type: o.column.type ?? null, notNull: o.column.notNull === true, default: o.column.default ?? null, comment: o.column.comment ?? null },
     expression: o.expression,
+    ...(o.reverse !== undefined ? { reverse: o.reverse } : {}),
+    ...(o.defaultAtContract ? { defaultAtContract: true } : {}),
     batchKey: o.batchKey,
     rules: o.changes.map((c) => c.rule),
     ...(o.carried.length > 0 || o.views.length > 0 || o.sequence ? { dependents: carriedSubject(o) } : {}),

package/src/postgres/migrate/op.ts

@@ -20,7 +20,7 @@
  * | Expand | add the new column, nullable, no default (a catalog change) |
  * | Dual write | a trigger that keeps the new column written: computed from the old one for a type change, both ways for a rename |
  * | Backfill | `UPDATE` per key range, each batch with its receipt in its own transaction, under `lock_timeout`, pausing while a replica is behind |
- * | Carry over | each index on the old column built again on the new one `CONCURRENTLY`, each check and foreign key (another table's too) added `NOT VALID` and validated (`./carry.ts`) |
+ * | Carry over | each index on the old column built again on the new one `CONCURRENTLY` (on a partitioned table: `ON ONLY` the table, `CONCURRENTLY` per partition, then attached), each check and foreign key (another table's too) added `NOT VALID` and validated (`./carry.ts`) |
  * | Verify | rows, mismatches and checksums of the new column against the old |
  * | Approve | a gate bound to the plan and the verified new column |
  * | Switch | NOT NULL proven by a validated check; then one short transaction: a type change swaps the columns by name, a rename finishes the new column; the carried indexes and constraints take their names (keys `USING INDEX`), and the views that read the column are made again from their declarations |
@@ -64,6 +64,29 @@ export interface PostgresMigrationOpConfig {
    * and the verification all use it.
    */
   using?: string;
+  /**
+   * A rename combined with a type change: the SQL expression that gives the
+   * old column's value from the new column's, over the row's columns (the
+   * new column by its declared name). `using` gives the new value from the
+   * old one. Both stay in force until the contract: a writer of the old name
+   * has `using` applied, a writer of the new name has `reverse` applied. The
+   * verification fails the run unless `reverse` over every new value gives
+   * the old value back. A new value the old type cannot hold fails the
+   * writer's statement until the contract drops the old column.
+   */
+  reverse?: string;
+  /**
+   * A rename of a column with a default, an identity or a serial sequence.
+   * The declared default (or identity, or the serial's default) lands on the
+   * new column at the contract, not at the switch, so that until then a
+   * writer of either name gets the old column's default once. Two writes
+   * differ from the declaration until then, and `true` accepts both: an
+   * INSERT that names the new column with an explicit NULL gets the default
+   * instead of NULL, and `UPDATE ... SET <new> = DEFAULT` sets NULL. An
+   * `ApplyOp` between the switch and the contract must not set the default
+   * on the new column. Needs `gates: "own"` to end with the contract.
+   */
+  defaultAtContract?: boolean;
   /** The build output the declaration is read from. Default: `dist/schema.json`. */
   output?: string;
   /** Project directory to build. Default: `.`. */
@@ -138,6 +161,8 @@ export interface PostgresMigrationArgs {
   buildPath: string;
   environment?: string;
   using?: string;
+  reverse?: string;
+  defaultAtContract?: boolean;
   retain?: string;
   batchSize?: number;
   replicationLag?: { max?: string; wait?: string } | false;
@@ -178,6 +203,8 @@ export function PostgresMigrationOp(config: PostgresMigrationOpConfig): Postgres
     buildPath: config.output ?? "dist/schema.json",
     environment: config.env,
     ...(config.using !== undefined ? { using: config.using } : {}),
+    ...(config.reverse !== undefined ? { reverse: config.reverse } : {}),
+    ...(config.defaultAtContract ? { defaultAtContract: true } : {}),
     ...(config.retain ? { retain: config.retain } : {}),
     ...(config.batchSize !== undefined ? { batchSize: config.batchSize } : {}),
     ...(config.replicationLag !== undefined ? { replicationLag: config.replicationLag } : {}),

package/src/postgres/migrate/partition.e2e.test.ts

@@ -0,0 +1,129 @@
+/**
+ * An index on a partitioned table's migrated column (#3333), against the
+ * pinned server: the Op builds it per partition and attaches it, and what
+ * stays refused.
+ *
+ * - `text` to `numeric` on a column with a plain index and a partial unique
+ *   index, on a table with a default partition, two partitions and a
+ *   sub-partitioned one: every partition's index is built `CONCURRENTLY`
+ *   (never under a lock that blocks writes), attached, and the partitioned
+ *   index is valid and named as declared after the switch.
+ * - A write while the Op waits at its gate lands in the new column.
+ * - A unique constraint on the column stays refused, naming why.
+ *
+ * Needs Docker; skips cleanly without it.
+ */
+
+import { mkdtempSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { afterAll, beforeAll, describe, expect, test } from "vitest";
+import { dockerAvailable, startTestPostgres, type TestPostgres } from "../testing/server";
+import { ApprovingLedger, runMigrationOp } from "../testing/migration";
+import type { PostgresClient } from "../live/client";
+import { planPgAgainstServer } from "../plan/commands";
+import { postgresApply } from "../../op/activities/postgres-apply";
+import { postgresMigrationPlan, type PostgresMigrationDeps } from "../../op/activities/postgres-migration";
+import type { PostgresMigrationOpConfig } from "./op";
+
+const enabled = await dockerAvailable();
+let server: TestPostgres | undefined;
+let admin: PostgresClient | undefined;
+const dir = mkdtempSync(join(tmpdir(), "chant-pg-partition-"));
+
+beforeAll(async () => {
+  if (!enabled) return;
+  server = await startTestPostgres();
+  admin = await server.connect();
+}, 600_000);
+
+afterAll(async () => {
+  await admin?.end();
+  await server?.stop();
+  rmSync(dir, { recursive: true, force: true });
+});
+
+interface Obj {
+  export: string;
+  type: string;
+  ddl: string;
+  dependsOn?: string[];
+}
+
+function writeBuild(file: string, objects: Obj[]): string {
+  writeFileSync(join(dir, file), JSON.stringify({ dialect: "postgres", postgresMajor: 18, applyOrder: objects.map((o) => o.export), objects: objects.map((o) => ({ dependsOn: [], ...o })) }));
+  return file;
+}
+
+const MARKER = { stack: "e2e", env: "test" };
+const profile = () => ({
+  config: { ownership: MARKER, sql: { profiles: { e2e: { url: server!.endpoint().url, password: { env: "PG_E2E_PASSWORD" } } } } },
+  env: { PG_E2E_PASSWORD: server!.endpoint().password },
+});
+const deps = (): PostgresMigrationDeps => ({ ...profile(), log: () => undefined });
+const apply = (file: string) => postgresApply({ buildPath: join(dir, file), environment: "e2e" }, undefined, { ...profile(), log: () => undefined });
+const plan = (file: string) => planPgAgainstServer("e2e", join(dir, file), profile());
+const one = async <T>(sql: string): Promise<T> => (await admin!.query<T>(sql))[0]!;
+const schemaObj = (name: string): Obj => ({ export: name, type: "Postgres::Schema", ddl: `CREATE SCHEMA ${name}` });
+const table = (exportName: string, schema: string, ddl: string, dependsOn: string[] = []): Obj => ({ export: exportName, type: "Postgres::Table", dependsOn: [schema, ...dependsOn], ddl });
+
+describe.skipIf(!enabled)("a plain and a partial unique index on a partitioned table's migrated column", () => {
+  const PI = schemaObj("pi");
+  const events = (t: string): Obj => table("events", "pi", `CREATE TABLE pi.events (id bigint, at date NOT NULL, amount ${t} NOT NULL, PRIMARY KEY (id, at)) PARTITION BY RANGE (at)`);
+  const part = (y: number): Obj => table(`events${y}`, "pi", `CREATE TABLE pi.events_${y} PARTITION OF pi.events FOR VALUES FROM ('${y}-01-01') TO ('${y + 1}-01-01')`, ["events"]);
+  const sub = table("events2027", "pi", "CREATE TABLE pi.events_2027 PARTITION OF pi.events FOR VALUES FROM ('2027-01-01') TO ('2028-01-01') PARTITION BY RANGE (at)", ["events"]);
+  const q1 = table("events2027q1", "pi", "CREATE TABLE pi.events_2027_q1 PARTITION OF pi.events_2027 FOR VALUES FROM ('2027-01-01') TO ('2027-04-01')", ["events2027"]);
+  const byAmount: Obj = { export: "eventsByAmount", type: "Postgres::Index", dependsOn: ["events"], ddl: "CREATE INDEX events_amount_idx ON pi.events (amount)" };
+  const uniq = (col: string): Obj => ({ export: "eventsUnique", type: "Postgres::Index", dependsOn: ["events"], ddl: `CREATE UNIQUE INDEX events_unique_idx ON pi.events (at, ${col}) WHERE id > 0` });
+  const objects = (t: string, col: string) => [PI, events(t), part(2025), part(2026), sub, q1, { ...byAmount, ddl: `CREATE INDEX events_amount_idx ON pi.events (${col})` }, uniq(col)];
+
+  test("each partition's index is built and attached, and the partitioned index takes its declared name", async () => {
+    await apply(writeBuild("pi-v1.json", objects("text", "amount")));
+    await admin!.query("INSERT INTO pi.events SELECT g, DATE '2025-01-01' + (g % 900), (g % 90) || '.5' FROM generate_series(1, 1500) g");
+    writeBuild("pi-v2.json", objects("numeric(10,2)", "amount"));
+
+    const ledger = new ApprovingLedger();
+    const config: PostgresMigrationOpConfig = { name: "migrate-events-amount", env: "e2e", table: "pi.events", column: "amount", build: false, path: dir, output: "pi-v2.json", retain: "0s", stack: MARKER.stack, ownershipEnv: MARKER.env, batchSize: 500 };
+    const statuses: string[] = [];
+    for (let i = 0; i < 4; i++) {
+      const r = await runMigrationOp(config, ledger.port, deps);
+      statuses.push(r.status);
+      if (i === 0) {
+        // Waiting at the gate: the partitioned working index is valid, every leaf partition has its own, and writes land in the new column.
+        expect(await one("SELECT indisvalid FROM pg_index WHERE indexrelid = 'pi.events_amount_idx__chant_new'::regclass")).toEqual({ indisvalid: true });
+        expect(await one("SELECT count(*)::int AS n FROM pg_index i JOIN pg_inherits h ON h.inhrelid = i.indexrelid WHERE h.inhparent = 'pi.events_amount_idx__chant_new'::regclass")).toEqual({ n: 3 });
+        await admin!.query("INSERT INTO pi.events VALUES (9000, DATE '2026-03-01', '2.25')");
+        expect(await one("SELECT amount__chant_new::text AS a FROM pi.events WHERE id = 9000")).toEqual({ a: "2.25" });
+      }
+      if (r.status !== "gated") break;
+      ledger.approveLast();
+    }
+    expect(statuses).toEqual(["gated", "gated", "ok"]);
+    expect(await one("SELECT i.indisvalid, c.relkind::text AS kind, pg_get_indexdef(c.oid) AS def FROM pg_index i JOIN pg_class c ON c.oid = i.indexrelid WHERE c.oid = 'pi.events_amount_idx'::regclass")).toEqual({
+      indisvalid: true,
+      kind: "I",
+      def: "CREATE INDEX events_amount_idx ON ONLY pi.events USING btree (amount)",
+    });
+    expect(await one("SELECT count(*)::int AS n FROM pg_class WHERE relnamespace = 'pi'::regnamespace AND relname LIKE '%\\_\\_chant\\_old'")).toEqual({ n: 0 });
+    // The query planner uses a partition's index on the new column.
+    await admin!.query("SET enable_seqscan = off");
+    expect(JSON.stringify(await admin!.query("EXPLAIN SELECT * FROM pi.events_2025 WHERE amount = 2.5"))).toContain("Index");
+    expect((await plan("pi-v2.json")).changes).toEqual([]);
+  }, 300_000);
+});
+
+describe.skipIf(!enabled)("a key on a partitioned table's migrated column", () => {
+  const PK = schemaObj("pk");
+  const events = (t: string): Obj => table("events", "pk", `CREATE TABLE pk.events (id bigint, at date NOT NULL, amount ${t} NOT NULL, PRIMARY KEY (id, at, amount)) PARTITION BY RANGE (at)`);
+  const part: Obj = table("events2025", "pk", "CREATE TABLE pk.events_2025 PARTITION OF pk.events FOR VALUES FROM ('2025-01-01') TO ('2026-01-01')", ["events"]);
+
+  test("stays refused, naming why", async () => {
+    await apply(writeBuild("pk-v1.json", [PK, events("text"), part]));
+    writeBuild("pk-v2.json", [PK, events("numeric(10,2)"), part]);
+    const message = await postgresMigrationPlan({ table: "pk.events", column: "amount", buildPath: "pk-v2.json", environment: "e2e", stack: MARKER.stack, ownershipEnv: MARKER.env, cwd: dir }, undefined, deps()).then(
+      () => "",
+      (e: unknown) => String((e as Error).message),
+    );
+    expect(message).toMatch(/primary key events_pkey on pk\.events: on a partitioned table a key cannot be attached from an index built CONCURRENTLY/);
+  }, 300_000);
+});

package/src/postgres/migrate/partition.test.ts

@@ -0,0 +1,206 @@
+/**
+ * An index on a partitioned table's migrated column (#3333), carried over
+ * per partition: the `ON ONLY` statement, each partition's `CONCURRENTLY`
+ * build, the attach, and a run that goes on from where the last stopped.
+ * The e2e is `partition.e2e.test.ts`.
+ */
+
+import { describe, expect, test } from "vitest";
+import type { PostgresClient } from "../live/client";
+import { carriedPartitionedIndexStatement, discoverDependents, partitionIndexName, partitionIndexStatement, type CarriedObject } from "./carry";
+import { migrationNames } from "./names";
+import { carryPartitionedIndex, type MigrationRun } from "./steps";
+
+const DEF = "CREATE INDEX events_amount_idx ON ONLY app.events USING btree (amount)";
+
+describe("the statements", () => {
+  test("a partitioned index is made again ON ONLY on the new column, without CONCURRENTLY", () => {
+    expect(carriedPartitionedIndexStatement(DEF, "events_amount_idx__chant_new", "amount", "amount__chant_new")).toBe("CREATE INDEX events_amount_idx__chant_new ON ONLY app.events USING btree (amount__chant_new)");
+    expect(carriedPartitionedIndexStatement("CREATE UNIQUE INDEX e ON ONLY app.events USING btree (id, amount) WHERE (amount > 0)", "e__chant_new", "amount", "login")).toBe(
+      "CREATE UNIQUE INDEX e__chant_new ON ONLY app.events USING btree (id, login) WHERE (login > 0)",
+    );
+    // Without ONLY in the definition, the statement still has it.
+    expect(carriedPartitionedIndexStatement("CREATE INDEX e ON app.events USING btree (amount)", "w", "amount", "n")).toBe("CREATE INDEX w ON ONLY app.events USING btree (n)");
+  });
+
+  test("a partition that holds rows gets a CONCURRENTLY build, one that is partitioned further gets ON ONLY", () => {
+    const c = { definition: "CREATE UNIQUE INDEX events_amount_idx__chant_new ON ONLY app.events USING btree (id, amount__chant_new) WHERE (amount__chant_new > 0)" };
+    expect(partitionIndexStatement(c, { ident: "app.events_2025", leaf: true }, "events_2025_events_amount_idx__chant_new")).toBe(
+      "CREATE UNIQUE INDEX CONCURRENTLY events_2025_events_amount_idx__chant_new ON app.events_2025 USING btree (id, amount__chant_new) WHERE (amount__chant_new > 0)",
+    );
+    expect(partitionIndexStatement(c, { ident: "app.events_2026", leaf: false }, "events_2026_x")).toBe(
+      "CREATE UNIQUE INDEX events_2026_x ON ONLY app.events_2026 USING btree (id, amount__chant_new) WHERE (amount__chant_new > 0)",
+    );
+  });
+
+  test("the partition's index name keeps within what Postgres keeps", () => {
+    expect(partitionIndexName({ name: "events_2025" }, "events_amount_idx__chant_new")).toBe("events_2025_events_amount_idx__chant_new");
+    expect(partitionIndexName({ name: "p".repeat(40) }, "i".repeat(40))).toHaveLength(63);
+  });
+});
+
+const names = migrationNames("app", "events", "amount", "type", "amount");
+const c: CarriedObject = {
+  kind: "index",
+  name: "events_amount_idx",
+  table: "app.events",
+  tableName: "app.events",
+  tableOid: "100",
+  schema: "app",
+  working: "events_amount_idx__chant_new",
+  target: "events_amount_idx",
+  definition: "CREATE INDEX events_amount_idx__chant_new ON ONLY app.events USING btree (amount__chant_new)",
+  validated: true,
+  partitioned: true,
+};
+
+interface Node {
+  oid: string;
+  name: string;
+  parent?: string;
+  leaf: boolean;
+  level: number;
+}
+
+/** A fake server for one partitioned index: the tree it has, and what of the working index exists already. */
+function server(tree: Node[], have: { root?: boolean; attached?: string[]; standalone?: Record<string, { valid: boolean; comment: string | null }> } = {}) {
+  const statements: string[] = [];
+  const indexOid = (name: string) => `i-${name}`;
+  const query = async (sql: string, params: unknown[] = []): Promise<Record<string, unknown>[]> => {
+    if (/^(CREATE|ALTER INDEX|COMMENT|DROP)/.test(sql)) statements.push(sql);
+    if (sql.includes("pg_partition_tree")) return tree.map((n) => ({ oid: n.oid, schema: "app", name: n.name, parent: n.parent ?? null, leaf: n.leaf, kind: n.leaf ? "r" : "p", level: n.level }));
+    if (sql.includes("AS oid") && sql.includes("to_regclass")) {
+      const ident = String(params[0]);
+      if (ident === "app.events_amount_idx__chant_new") return [{ oid: have.root ? "root" : null }];
+      return [{ oid: null }];
+    }
+    if (sql.includes("FROM pg_catalog.pg_inherits h")) {
+      const parent = String(params[0]);
+      const partition = String(params[1]);
+      const hit = tree.find((n) => n.oid === partition);
+      if (parent === "root" && hit && have.attached?.includes(hit.name)) return [{ oid: indexOid(hit.name), schema: "app", name: `${hit.name}_auto_idx` }];
+      return [];
+    }
+    if (sql.includes("indisvalid AS valid")) {
+      const ident = String(params[0]);
+      const name = /\.(.+)$/.exec(ident)![1]!;
+      const s = have.standalone?.[name];
+      return s ? [{ valid: s.valid, comment: s.comment }] : [];
+    }
+    return [];
+  };
+  const run = { client: { query } as unknown as PostgresClient, target: { defaultSchema: "app" }, lockTimeoutMs: 1000, statementTimeoutMs: 1000, log: () => undefined } as unknown as MigrationRun;
+  return { run, statements: () => statements };
+}
+
+const TREE: Node[] = [
+  { oid: "100", name: "events", leaf: false, level: 0 },
+  { oid: "101", name: "events_2025", parent: "100", leaf: true, level: 1 },
+  { oid: "102", name: "events_2026", parent: "100", leaf: true, level: 1 },
+];
+
+describe("carrying a partitioned index over", () => {
+  test("ON ONLY first, each partition's index built CONCURRENTLY, then each attached", async () => {
+    const s = server(TREE);
+    expect(await carryPartitionedIndex(s.run, names, c, "the comment", undefined)).toBe(true);
+    const sql = s.statements();
+    expect(sql[0]).toBe(c.definition);
+    expect(sql[1]).toMatch(/^COMMENT ON INDEX app\.events_amount_idx__chant_new IS /);
+    expect(sql.filter((x) => x.startsWith("CREATE"))).toEqual([
+      c.definition,
+      "CREATE INDEX CONCURRENTLY events_2025_events_amount_idx__chant_new ON app.events_2025 USING btree (amount__chant_new)",
+      "CREATE INDEX CONCURRENTLY events_2026_events_amount_idx__chant_new ON app.events_2026 USING btree (amount__chant_new)",
+    ]);
+    const attaches = sql.filter((x) => x.startsWith("ALTER INDEX"));
+    expect(attaches).toEqual([
+      "ALTER INDEX app.events_amount_idx__chant_new ATTACH PARTITION app.events_2025_events_amount_idx__chant_new",
+      "ALTER INDEX app.events_amount_idx__chant_new ATTACH PARTITION app.events_2026_events_amount_idx__chant_new",
+    ]);
+    // Every attach comes after every build, and each partition's index carries the migration's trailer.
+    expect(sql.lastIndexOf(sql.filter((x) => x.startsWith("CREATE")).at(-1)!)).toBeLessThan(sql.indexOf(attaches[0]!));
+    expect(sql.filter((x) => x.startsWith("COMMENT ON INDEX app.events_2025_")).join()).toContain("migration=app.events.amount role=carry");
+  });
+
+  test("a run after a crash keeps the partitions already attached, drops an invalid build and goes on", async () => {
+    const s = server(TREE, { root: true, attached: ["events_2025"], standalone: { events_2026_events_amount_idx__chant_new: { valid: false, comment: null } } });
+    const state = { present: true, ready: false, marked: true };
+    await carryPartitionedIndex(s.run, names, c, "the comment", state);
+    const sql = s.statements();
+    expect(sql.some((x) => x.includes("events_2025"))).toBe(false);
+    expect(sql.filter((x) => !x.startsWith("COMMENT"))).toEqual([
+      "DROP INDEX CONCURRENTLY IF EXISTS app.events_2026_events_amount_idx__chant_new",
+      "CREATE INDEX CONCURRENTLY events_2026_events_amount_idx__chant_new ON app.events_2026 USING btree (amount__chant_new)",
+      "ALTER INDEX app.events_amount_idx__chant_new ATTACH PARTITION app.events_2026_events_amount_idx__chant_new",
+    ]);
+  });
+
+  test("a valid partitioned index that is marked is left alone", async () => {
+    const s = server(TREE, { root: true });
+    expect(await carryPartitionedIndex(s.run, names, c, "the comment", { present: true, ready: true, marked: true })).toBe(false);
+    expect(s.statements()).toEqual([]);
+  });
+
+  test("a partition that is partitioned further gets ON ONLY, and is attached after its own partitions", async () => {
+    const tree: Node[] = [
+      { oid: "100", name: "events", leaf: false, level: 0 },
+      { oid: "101", name: "events_2025", parent: "100", leaf: false, level: 1 },
+      { oid: "103", name: "events_2025_q1", parent: "101", leaf: true, level: 2 },
+    ];
+    const s = server(tree);
+    await carryPartitionedIndex(s.run, names, c, "the comment", undefined);
+    const sql = s.statements().filter((x) => !x.startsWith("COMMENT"));
+    expect(sql).toEqual([
+      c.definition,
+      "CREATE INDEX events_2025_events_amount_idx__chant_new ON ONLY app.events_2025 USING btree (amount__chant_new)",
+      "CREATE INDEX CONCURRENTLY events_2025_q1_events_amount_idx__chant_new ON app.events_2025_q1 USING btree (amount__chant_new)",
+      "ALTER INDEX app.events_2025_events_amount_idx__chant_new ATTACH PARTITION app.events_2025_q1_events_amount_idx__chant_new",
+      "ALTER INDEX app.events_amount_idx__chant_new ATTACH PARTITION app.events_2025_events_amount_idx__chant_new",
+    ]);
+  });
+});
+
+describe("finding a partitioned index on the column", () => {
+  const find = async (tree: Array<{ name: string; kind: string }>, row: Record<string, unknown> = {}) => {
+    const query = async (sql: string): Promise<Record<string, unknown>[]> => {
+      if (sql.includes("pg_catalog.pg_depend d") && sql.includes("UNION")) return [{ kind: "class", objid: "9", objsubid: 0, what: "index", deptype: "n" }];
+      if (sql.includes("AS has_exprs")) {
+        return [{ oid: "9", name: "events_amount_idx", kind: "I", schema: "app", comment: null, def: DEF, valid: true, is_unique: false, replident: false, clustered: false, cols: ["amount"], has_exprs: false, ...row }];
+      }
+      if (sql.includes("pg_partition_tree")) return tree.map((t, i) => ({ oid: String(100 + i), schema: "app", name: t.name, parent: i === 0 ? null : "100", leaf: i > 0, kind: t.kind, level: i === 0 ? 0 : 1 }));
+      return [];
+    };
+    return discoverDependents({
+      client: { query } as unknown as PostgresClient,
+      names: migrationNames("app", "events", "amount", "type", "amount"),
+      oid: "100",
+      attnum: 3,
+      objects: [],
+      declared: { props: {}, canonical: { schema: "app", name: "events" } } as never,
+      defaultSchema: "app",
+      partitioned: true,
+    });
+  };
+
+  test("it is carried over, as a partitioned index", async () => {
+    const d = await find([{ name: "events", kind: "p" }, { name: "events_2025", kind: "r" }]);
+    expect(d.refused).toEqual([]);
+    expect(d.carried).toHaveLength(1);
+    expect(d.carried[0]).toMatchObject({
+      kind: "index",
+      partitioned: true,
+      working: "events_amount_idx__chant_new",
+      definition: "CREATE INDEX events_amount_idx__chant_new ON ONLY app.events USING btree (amount__chant_new)",
+    });
+  });
+
+  test("a foreign table among the partitions refuses it, naming the partition", async () => {
+    const d = await find([{ name: "events", kind: "p" }, { name: "events_remote", kind: "f" }]);
+    expect(d.carried).toEqual([]);
+    expect(d.refused).toEqual([expect.stringMatching(/partitioned index app\.events_amount_idx: app\.events_remote is a foreign table/)]);
+  });
+
+  test("an INVALID one (an ON ONLY never finished) still refuses", async () => {
+    const d = await find([{ name: "events", kind: "p" }], { valid: false });
+    expect(d.refused).toEqual([expect.stringMatching(/index app\.events_amount_idx is INVALID/)]);
+  });
+});