@intentius/chant-lexicon-sql 0.124.46 → 0.124.48

package/src/postgres/migrate/carry.ts

@@ -10,6 +10,7 @@
  * | On the old column | Before the switch | In the switch's transaction |
  * |---|---|---|
  * | an index | `CREATE INDEX CONCURRENTLY` on the new column | the old one dropped (a type change) or kept as `<name>__chant_old` (a rename), the new one renamed to the name |
+ * | an index on a partitioned table | `CREATE INDEX ... ON ONLY` the table, `CONCURRENTLY` on each partition, `ALTER INDEX ... ATTACH PARTITION` | as an index; the partitions' indexes go with the old one |
  * | a primary key or unique constraint | its unique index built `CONCURRENTLY` | the old constraint dropped (or a rename's unique one kept as `__chant_old`), `ADD CONSTRAINT ... USING INDEX` |
  * | a check or foreign key, this table's or another's that references the column | added `NOT VALID`, then `VALIDATE` | the old one dropped, the new one renamed to the name |
  * | a view (and the views that read it) | nothing | dropped, then created again from its declaration once the columns are swapped, with its grants and owner |
@@ -33,7 +34,8 @@
  * key or index the build declares on the new column takes the declared name.
  *
  * Refused, each named with what to do: exclusion constraints and constraint
- * triggers (no `USING INDEX` form), materialized views (made again only by
+ * triggers (no `USING INDEX` form), a key or foreign key on a partitioned table,
+ * a partitioned index over a foreign-table partition, materialized views (made again only by
  * a full scan in the switch), rules, triggers, policies and statistics on the
  * column, a generated column computed from it, an INVALID index on it, a view
  * the build does not declare, a view something other than a view depends on.
@@ -84,6 +86,12 @@ export interface CarriedObject {
   indexComment?: string;
   replicaIdentity?: boolean;
   clustered?: boolean;
+  /**
+   * An index on a partitioned table (#3333): `definition` is the `CREATE INDEX ... ON ONLY` that makes the
+   * partitioned index without building anything. Each partition's index is built `CONCURRENTLY` on its own and
+   * attached (`partitionIndexStatement`, `carryPartitionedIndex` in `./steps.ts`).
+   */
+  partitioned?: boolean;
 }
 
 /** A view on the old column (or on such a view), made again at the switch from its declaration. */
@@ -187,6 +195,73 @@ export function carriedIndexStatement(def: string, working: string, from: string
   return `CREATE ${m[1] ?? ""}INDEX CONCURRENTLY ${quoteIdent(working)} ON ${replaceColumn(m[2]!, from, to)}`;
 }
 
+/**
+ * A partitioned index (`pg_get_indexdef` prints it `ON ONLY`) as the
+ * `CREATE INDEX ... ON ONLY` of `working` on the new column: it builds nothing
+ * and stays INVALID until every partition's index is attached.
+ */
+export function carriedPartitionedIndexStatement(def: string, working: string, from: string, to: string): string {
+  const m = /^CREATE (UNIQUE )?INDEX (?:"(?:[^"]|"")+"|\S+) ON (?:ONLY )?(.*)$/s.exec(def);
+  if (!m) throw new Error(`unexpected index definition: ${def}`);
+  return `CREATE ${m[1] ?? ""}INDEX ${quoteIdent(working)} ON ONLY ${replaceColumn(m[2]!, from, to)}`;
+}
+
+/** One table of a partition tree. */
+export interface PartitionNode {
+  oid: string;
+  schema: string;
+  name: string;
+  /** Quoted and qualified. */
+  ident: string;
+  /** The partitioned table (or partition) it is a partition of; absent for the root. */
+  parent?: string;
+  /** Not partitioned further: the tables that hold rows. */
+  leaf: boolean;
+  /** `r` (ordinary), `p` (partitioned) or `f` (foreign). */
+  kind: string;
+  level: number;
+}
+
+/** The partition tree under a partitioned table, the table itself first (level 0). */
+export async function partitionTree(client: Pick<PostgresClient, "query">, tableOid: string): Promise<PartitionNode[]> {
+  const rows = await client.query<{ oid: string; schema: string; name: string; parent: string | null; leaf: boolean; kind: string; level: number }>(
+    `SELECT t.relid::oid::text AS oid, n.nspname AS schema, c.relname AS name, t.parentrelid::oid::text AS parent, t.isleaf AS leaf, c.relkind::text AS kind, t.level
+     FROM pg_catalog.pg_partition_tree($1::oid::pg_catalog.regclass) t JOIN pg_catalog.pg_class c ON c.oid = t.relid JOIN pg_catalog.pg_namespace n ON n.oid = c.relnamespace
+     ORDER BY t.level, n.nspname, c.relname`,
+    [tableOid],
+  );
+  return rows.map((r) => ({
+    oid: String(r.oid),
+    schema: r.schema,
+    name: r.name,
+    ident: `${quoteIdent(r.schema)}.${quoteIdent(r.name)}`,
+    ...(r.parent !== null ? { parent: String(r.parent) } : {}),
+    leaf: r.leaf === true,
+    kind: r.kind,
+    level: Number(r.level),
+  }));
+}
+
+/** The name of the index a partitioned index's working copy has on one partition. */
+export const partitionIndexName = (partition: Pick<PartitionNode, "name">, working: string): string => pgName(`${partition.name}_${working}`);
+
+/**
+ * The statement that makes a partitioned index's working copy on one
+ * partition. A partition that is partitioned further gets `ON ONLY` (it is
+ * valid once its own partitions are attached); one that holds rows gets the
+ * `CONCURRENTLY` build, so writes go on.
+ */
+export function partitionIndexStatement(c: Pick<CarriedObject, "definition">, node: Pick<PartitionNode, "ident" | "leaf">, indexName: string): string {
+  const m = /^CREATE (UNIQUE )?INDEX (?:"(?:[^"]|"")+"|\S+) ON ONLY (.*)$/s.exec(c.definition);
+  if (!m) throw new Error(`unexpected partitioned index definition: ${c.definition}`);
+  const using = m[2]!.indexOf(" USING ");
+  if (using < 0) throw new Error(`unexpected partitioned index definition: ${c.definition}`);
+  const tail = m[2]!.slice(using);
+  return node.leaf
+    ? `CREATE ${m[1] ?? ""}INDEX CONCURRENTLY ${quoteIdent(indexName)} ON ${node.ident}${tail}`
+    : `CREATE ${m[1] ?? ""}INDEX ${quoteIdent(indexName)} ON ONLY ${node.ident}${tail}`;
+}
+
 /**
  * The name Postgres gives an object it names after its columns
  * (`users_email_key`, `orders_user_id_fkey`, `users_email_idx`), when `name`
@@ -214,12 +289,26 @@ interface DiscoverInput {
   defaultSchema: string;
   /** The table is partitioned: its indexes cannot be built CONCURRENTLY, nor its keys attached USING INDEX. */
   partitioned?: boolean;
+  /** A rename keeps the column's sequence on the old column until the contract (`defaultAtContract`), instead of being refused. */
+  keepSequence?: boolean;
 }
 
 interface Row {
   [key: string]: unknown;
 }
 
+/** The sequence that belongs to a column (an identity's, or a `serial`'s), if it has one. */
+export async function columnSequence(client: PostgresClient, tableOid: string, attnum: number): Promise<ColumnSequence | undefined> {
+  const [row] = await client.query<{ schema: string; name: string; deptype: string }>(
+    `SELECT n.nspname AS schema, c.relname AS name, d.deptype::text AS deptype
+     FROM pg_catalog.pg_depend d JOIN pg_catalog.pg_class c ON c.oid = d.objid AND d.classid = 'pg_catalog.pg_class'::pg_catalog.regclass JOIN pg_catalog.pg_namespace n ON n.oid = c.relnamespace
+     WHERE d.refclassid = 'pg_catalog.pg_class'::pg_catalog.regclass AND d.refobjid = $1::oid AND d.refobjsubid = $2 AND d.deptype IN ('a', 'i') AND c.relkind = 'S'`,
+    [tableOid, attnum],
+  );
+  if (!row) return undefined;
+  return { kind: row.deptype === "i" ? "identity" : "serial", schema: row.schema, name: row.name, ident: `${quoteIdent(row.schema)}.${quoteIdent(row.name)}` };
+}
+
 /** What uses the column the values come from, sorted into what the Op carries over and what it refuses. */
 export async function discoverDependents(input: DiscoverInput): Promise<Dependents> {
   const { client, names: n, oid, attnum } = input;
@@ -343,10 +432,6 @@ export async function discoverDependents(input: DiscoverInput): Promise<Dependen
       const kind = String(r.kind);
       if (kind === "i" || kind === "I") {
         if (keyIndexes.has(String(r.oid))) continue;
-        if (kind === "I") {
-          refused.push(`index ${r.schema}.${name} is a partitioned index, which cannot be built CONCURRENTLY; drop it, migrate, then declare it again (chant #3333)`);
-          continue;
-        }
         if (r.valid !== true) {
           refused.push(`index ${r.schema}.${name} is INVALID (a failed CONCURRENTLY build); drop it, or REINDEX it, first`);
           continue;
@@ -375,6 +460,14 @@ export async function discoverDependents(input: DiscoverInput): Promise<Dependen
                 });
           target = declaredIndex?.canonical.name ?? (r.has_exprs === true ? undefined : renamedDefault(name, table, oldCols, cols, "idx")) ?? name;
         }
+        if (kind === "I") {
+          // A partition the index cannot be built on (a foreign table) stops the carry before anything is made.
+          const foreign = (await partitionTree(client, oid)).filter((p) => p.kind === "f");
+          if (foreign.length > 0) {
+            refused.push(`partitioned index ${r.schema}.${name}: ${foreign.map((p) => `${p.schema}.${p.name}`).join(", ")} is a foreign table, which holds no index to attach; drop the index, migrate, then declare it again`);
+            continue;
+          }
+        }
         carried.push({
           kind: "index",
           name,
@@ -384,7 +477,8 @@ export async function discoverDependents(input: DiscoverInput): Promise<Dependen
           schema: String(r.schema),
           working,
           target,
-          definition: carriedIndexStatement(String(r.def), working, from, to),
+          definition: kind === "I" ? carriedPartitionedIndexStatement(String(r.def), working, from, to) : carriedIndexStatement(String(r.def), working, from, to),
+          ...(kind === "I" ? { partitioned: true } : {}),
           validated: true,
           ...(r.comment !== null ? { comment: String(r.comment) } : {}),
           ...(r.replident === true ? { replicaIdentity: true } : {}),
@@ -393,9 +487,10 @@ export async function discoverDependents(input: DiscoverInput): Promise<Dependen
       } else if (kind === "S") {
         const dep = deps.find((d) => d.kind === "class" && d.objid === String(r.oid));
         const seq: ColumnSequence = { kind: dep?.deptype === "i" ? "identity" : "serial", schema: String(r.schema), name, ident: `${quoteIdent(String(r.schema))}.${quoteIdent(name)}` };
-        if (rename) {
+        if (rename && !input.keepSequence) {
           refused.push(
-            `sequence ${r.schema}.${name} gives the column its values (${seq.kind === "identity" ? "an identity column" : "a serial column's default"}); during a rename a writer that names the new column would be given the old one's next value by the trigger, which it cannot tell from a value the writer chose; a rename that keeps its sequence needs versioned views (chant #3331)`,
+            `sequence ${r.schema}.${name} gives the column its values (${seq.kind === "identity" ? "an identity column" : "a serial column's default"}); during a rename a writer that names the new column would get the old one's next value, and the trigger would take it over the writer's, ` +
+              `because it cannot tell a defaulted value from one the writer gave. Set defaultAtContract: true to leave the new column without the default until the contract (see the Op's reference), or drop the default first`,
           );
         } else sequence = seq;
       } else {

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

@@ -0,0 +1,218 @@
+/**
+ * Renames the Op refused in #3322 and makes since (#3331), against the
+ * pinned server:
+ *
+ * - A rename of a column with a default (`defaultAtContract`): writers of
+ *   either name during the migration, the new column without the default
+ *   until the contract, and the default there once it ends.
+ * - A rename of a `serial` column: the sequence stays on the old column
+ *   until the contract and is handed to the new one there.
+ * - A rename of an identity column: the identity moves to the new column at
+ *   the contract and carries on where the old one stood.
+ * - A rename with a type change (`reverse`): writers of either name, and a
+ *   `reverse` that does not give the old value back fails the verification.
+ *
+ * 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 { OpRunFailure } from "@intentius/chant/op";
+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-followups-"));
+
+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): Obj => ({ export: exportName, type: "Postgres::Table", dependsOn: [schema], ddl });
+/** A table of a `bigint` key and one more column, last, with the `-- previously:` hint a rename is declared by. */
+const keyed = (exportName: string, schema: string, column: string, previously?: string): Obj =>
+  table(exportName, schema, `CREATE TABLE ${schema}.${exportName} (\n  id bigint PRIMARY KEY,\n  ${column}${previously ? ` -- previously: ${previously}` : ""}\n)`);
+const config = (over: Pick<PostgresMigrationOpConfig, "name" | "table" | "column" | "output"> & Partial<PostgresMigrationOpConfig>): PostgresMigrationOpConfig => ({
+  env: "e2e",
+  build: false,
+  path: dir,
+  retain: "0s",
+  stack: MARKER.stack,
+  ownershipEnv: MARKER.env,
+  ...over,
+});
+const refusal = (tableName: string, column: string, output: string, extra: Partial<PostgresMigrationOpConfig> = {}) =>
+  postgresMigrationPlan({ table: tableName, column, buildPath: output, environment: "e2e", stack: MARKER.stack, ownershipEnv: MARKER.env, cwd: dir, ...extra } as never, undefined, deps()).then(
+    () => "",
+    (e: unknown) => String((e as Error).message),
+  );
+const defaultOf = async (t: string, c: string) =>
+  (await one<{ d: string | null }>(`SELECT pg_catalog.pg_get_expr(d.adbin, d.adrelid) AS d FROM pg_catalog.pg_attribute a LEFT JOIN pg_catalog.pg_attrdef d ON d.adrelid = a.attrelid AND d.adnum = a.attnum WHERE a.attrelid = '${t}'::regclass AND a.attname = '${c}'`)).d;
+
+/** Run the Op until it is done, approving each gate; `atGate` runs after the first run, with both columns written and nothing switched. */
+async function runToEnd(c: PostgresMigrationOpConfig, atGate?: () => Promise<void>) {
+  const ledger = new ApprovingLedger();
+  const runs = [];
+  for (let i = 0; i < 4; i++) {
+    const r = await runMigrationOp(c, ledger.port, deps);
+    runs.push(r);
+    if (i === 0) await atGate?.();
+    if (r.status !== "gated") break;
+    ledger.approveLast();
+  }
+  return runs;
+}
+
+describe.skipIf(!enabled)("a rename of a column with a default", () => {
+  const DF = schemaObj("df");
+  const users = (c: string, previously?: string) => keyed("users", "df", `${c} text NOT NULL DEFAULT 'none'`, previously);
+
+  test("refused without defaultAtContract; with it, writers of either name agree and the default lands at the contract", async () => {
+    await apply(writeBuild("df-v1.json", [DF, users("email")]));
+    await admin!.query("INSERT INTO df.users (id, email) SELECT g, 'u' || g FROM generate_series(1, 500) g");
+    writeBuild("df-v2.json", [DF, users("login", "email")]);
+    expect(await refusal("df.users", "login", "df-v2.json")).toMatch(/Set defaultAtContract: true/);
+
+    const runs = await runToEnd(config({ name: "migrate-df-login", table: "df.users", column: "login", output: "df-v2.json", defaultAtContract: true, batchSize: 200 }), async () => {
+      // Nothing is switched: the new column has no default, the old one keeps its own.
+      expect(await defaultOf("df.users", "login")).toBeNull();
+      expect(await defaultOf("df.users", "email")).toBe("'none'::text");
+      await admin!.query("INSERT INTO df.users (id) VALUES (1001)"); // neither name
+      await admin!.query("INSERT INTO df.users (id, email) VALUES (1002, 'old')"); // the old name
+      await admin!.query("INSERT INTO df.users (id, login) VALUES (1003, 'new')"); // the new name
+      await admin!.query("UPDATE df.users SET login = 'new2' WHERE id = 1002");
+      await admin!.query("UPDATE df.users SET email = 'old2' WHERE id = 1003");
+    });
+    expect(runs.map((r) => r.status)).toEqual(["gated", "gated", "ok"]);
+    expect(await admin!.query("SELECT id::int AS id, login FROM df.users WHERE id > 1000 ORDER BY id")).toEqual([
+      { id: 1001, login: "none" },
+      { id: 1002, login: "new2" },
+      { id: 1003, login: "old2" },
+    ]);
+    expect(await defaultOf("df.users", "login")).toBe("'none'::text");
+    expect(await admin!.query("SELECT attname FROM pg_attribute WHERE attrelid = 'df.users'::regclass AND attnum > 0 AND NOT attisdropped ORDER BY attnum")).toEqual([{ attname: "id" }, { attname: "login" }]);
+    expect((await plan("df-v2.json")).changes).toEqual([]);
+  }, 300_000);
+});
+
+describe.skipIf(!enabled)("a rename of a serial column", () => {
+  const SR = schemaObj("sq");
+  const items = (c: string, previously?: string) => keyed("items", "sq", `${c} serial`, previously);
+
+  test("the sequence stays with the old column until the contract, then belongs to the new one and stays its default", async () => {
+    await apply(writeBuild("sq-v1.json", [SR, items("n")]));
+    await admin!.query("INSERT INTO sq.items (id) SELECT g FROM generate_series(1, 300) g");
+    writeBuild("sq-v2.json", [SR, items("num", "n")]);
+
+    const runs = await runToEnd(config({ name: "migrate-items-num", table: "sq.items", column: "num", output: "sq-v2.json", defaultAtContract: true }), async () => {
+      await admin!.query("INSERT INTO sq.items (id) VALUES (1001)"); // takes the old default; the trigger copies it
+      await admin!.query("INSERT INTO sq.items (id, num) VALUES (1002, 7000)"); // the new name
+      expect(await one("SELECT n = num AS same FROM sq.items WHERE id = 1001")).toEqual({ same: true });
+      expect(await one("SELECT n AS n FROM sq.items WHERE id = 1002")).toEqual({ n: 7000 });
+    });
+    expect(runs.map((r) => r.status)).toEqual(["gated", "gated", "ok"]);
+    expect(await one("SELECT pg_catalog.pg_get_serial_sequence('sq.items', 'num') AS seq")).toEqual({ seq: "sq.items_n_seq" });
+    const next = await one<{ id: number; num: number }>("INSERT INTO sq.items (id) VALUES (2000) RETURNING id::int AS id, num");
+    expect(next.num).toBeGreaterThan(300);
+    expect((await plan("sq-v2.json")).changes).toEqual([]);
+  }, 300_000);
+});
+
+describe.skipIf(!enabled)("a rename of an identity column", () => {
+  const ID = schemaObj("ix");
+  const things = (c: string, previously?: string) => keyed("things", "ix", `${c} integer GENERATED ALWAYS AS IDENTITY`, previously);
+
+  test("the identity moves to the new column at the contract and carries on where the old one stood", async () => {
+    await apply(writeBuild("ix-v1.json", [ID, things("n")]));
+    await admin!.query("INSERT INTO ix.things (id) SELECT g FROM generate_series(1, 120) g");
+    writeBuild("ix-v2.json", [ID, things("num", "n")]);
+
+    const runs = await runToEnd(config({ name: "migrate-things-num", table: "ix.things", column: "num", output: "ix-v2.json", defaultAtContract: true }), async () => {
+      await admin!.query("INSERT INTO ix.things (id) VALUES (1001)"); // the old identity gives 121; the trigger copies it
+      expect(await one("SELECT n = num AS same FROM ix.things WHERE id = 1001")).toEqual({ same: true });
+      // A writer of the new name gives a value; the trigger sets the old column's ALWAYS identity from it.
+      await admin!.query("INSERT INTO ix.things (id, num) VALUES (1002, 5000)");
+      expect(await one("SELECT n AS n FROM ix.things WHERE id = 1002")).toEqual({ n: 5000 });
+    });
+    expect(runs.map((r) => r.status)).toEqual(["gated", "gated", "ok"]);
+    expect(await one("SELECT attidentity::text AS identity FROM pg_attribute WHERE attrelid = 'ix.things'::regclass AND attname = 'num'")).toEqual({ identity: "a" });
+    const next = await one<{ num: number }>("INSERT INTO ix.things (id) VALUES (2000) RETURNING num");
+    expect(next.num).toBeGreaterThan(120);
+    expect((await plan("ix-v2.json")).changes).toEqual([]);
+  }, 300_000);
+});
+
+describe.skipIf(!enabled)("a rename with a type change", () => {
+  const RT = schemaObj("rt");
+  const people = (column: string, previously?: string) => keyed("people", "rt", column, previously);
+
+  test("refused without reverse; with it, writers of either name agree and a wrong reverse fails the verification", async () => {
+    await apply(writeBuild("rt-v1.json", [RT, people("age_text text NOT NULL")]));
+    await admin!.query("INSERT INTO rt.people SELECT g, (g % 90)::text FROM generate_series(1, 400) g");
+    writeBuild("rt-v2.json", [RT, people("age integer NOT NULL", "age_text")]);
+    expect(await refusal("rt.people", "age", "rt-v2.json")).toMatch(/give that expression as reverse/);
+
+    // A reverse that does not give the old value back: nothing is switched and onFailure drops what the expand added.
+    const bad = await runMigrationOp(config({ name: "migrate-people-age", table: "rt.people", column: "age", output: "rt-v2.json", using: "CAST(age_text AS integer)", reverse: "CAST(age AS text) || 'x'" }), new ApprovingLedger().port, deps).then(
+      () => undefined,
+      (e: unknown) => e,
+    );
+    expect(bad).toBeInstanceOf(OpRunFailure);
+    expect((bad as OpRunFailure).result.records.find((x) => x.fn === "postgresMigrationVerify")?.error).toMatch(/must give the old value back/);
+    expect(await one("SELECT count(*)::int AS n FROM pg_attribute WHERE attrelid = 'rt.people'::regclass AND attname = 'age' AND NOT attisdropped")).toEqual({ n: 0 });
+
+    const runs = await runToEnd(config({ name: "migrate-people-age", table: "rt.people", column: "age", output: "rt-v2.json", using: "CAST(age_text AS integer)", reverse: "CAST(age AS text)" }), async () => {
+      await admin!.query("INSERT INTO rt.people (id, age_text) VALUES (1001, '41')"); // the old name
+      await admin!.query("INSERT INTO rt.people (id, age) VALUES (1002, 42)"); // the new name
+      await admin!.query("UPDATE rt.people SET age = 43 WHERE id = 1001");
+      await admin!.query("UPDATE rt.people SET age_text = '44' WHERE id = 1002");
+      expect(await admin!.query("SELECT id::int AS id, age, age_text FROM rt.people WHERE id > 1000 ORDER BY id")).toEqual([
+        { id: 1001, age: 43, age_text: "43" },
+        { id: 1002, age: 44, age_text: "44" },
+      ]);
+    });
+    expect(runs.map((r) => r.status)).toEqual(["gated", "gated", "ok"]);
+    expect(await one("SELECT pg_catalog.format_type(atttypid, atttypmod) AS t FROM pg_attribute WHERE attrelid = 'rt.people'::regclass AND attname = 'age'")).toEqual({ t: "integer" });
+    expect(await admin!.query("SELECT attname FROM pg_attribute WHERE attrelid = 'rt.people'::regclass AND attnum > 0 AND NOT attisdropped ORDER BY attnum")).toEqual([{ attname: "id" }, { attname: "age" }]);
+    expect((await plan("rt-v2.json")).changes).toEqual([]);
+  }, 300_000);
+});

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

@@ -0,0 +1,199 @@
+/**
+ * The migration Op's follow-ups to #3322 that need no server (#3331): a
+ * rename combined with a type change (`reverse`), and a rename of a column
+ * with a default, a serial or an identity (`defaultAtContract`). The dual
+ * write's body, the contract's statements and the refusals; the e2e is
+ * `followups.e2e.test.ts`.
+ */
+
+import { describe, expect, test } from "vitest";
+import { validateActivitySteps, collectActivityContracts, loadActivityContracts, mergeActivityContracts, type ActivityContract, type OpConfig } from "@intentius/chant/op";
+import * as contractsModule from "../../op/activity-contracts";
+import type { PostgresClient } from "../live/client";
+import type { PgChange } from "../plan/diff";
+import { PostgresMigrationOp, type PostgresMigrationOpConfig } from "./op";
+import { migrationNames } from "./names";
+import { dualWriteBody, contractStatements } from "./steps";
+import { migrationPlanSubject, refuseUnsupported, type MigrationObservation, type RelationRow, type ServerColumn } from "./observe";
+
+const BASE: PostgresMigrationOpConfig = { name: "migrate-users-login", env: "prod", table: "app.users", column: "login", build: false };
+const propsOf = (config: PostgresMigrationOpConfig) => (PostgresMigrationOp(config).op as unknown as { props: OpConfig }).props;
+
+const names = migrationNames("app", "users", "login", "rename", "email");
+
+const observation = (over: Partial<MigrationObservation> = {}): MigrationObservation =>
+  ({
+    state: "switched",
+    names,
+    declared: {} as MigrationObservation["declared"],
+    column: { name: "login", type: "text" },
+    oid: "16384",
+    batchKey: "id",
+    keyColumns: [{ name: "id", type: "bigint" }],
+    carried: [],
+    carriedStates: new Map(),
+    views: [],
+    partitioned: false,
+    columns: new Map(),
+    changes: [],
+    expression: '"email"',
+    publications: [],
+    major: 18,
+    old: { attnum: 2, name: "email", type: "text", notNull: true, generated: false, identity: false },
+    trigger: { name: names.trigger },
+    fn: { name: names.fn },
+    ...over,
+  }) as MigrationObservation;
+
+describe("a rename with a type change", () => {
+  const retyped = migrationNames("app", "users", "age", "rename", "age_text");
+  const o = { names: retyped, expression: "CAST(age_text AS integer)", reverse: "CAST(age AS text)" };
+
+  test("a writer of the old name has the expression applied, a writer of the new name the reverse", () => {
+    const body = dualWriteBody(o);
+    expect(body).toContain("IF NEW.age IS NULL THEN NEW.age := (SELECT CAST(age_text AS integer) FROM (SELECT NEW.*) AS users); ELSE NEW.age_text := (SELECT CAST(age AS text) FROM (SELECT NEW.*) AS users); END IF;");
+    expect(body).toContain("ELSIF NEW.age IS DISTINCT FROM OLD.age THEN\n    NEW.age_text := (SELECT CAST(age AS text) FROM (SELECT NEW.*) AS users);");
+    expect(body).toContain("ELSE\n    NEW.age := (SELECT CAST(age_text AS integer) FROM (SELECT NEW.*) AS users);");
+  });
+
+  test("a plain rename's body is unchanged", () => {
+    expect(dualWriteBody({ names, expression: '"email"' })).toContain("IF NEW.login IS NULL THEN NEW.login := NEW.email; ELSE NEW.email := NEW.login; END IF;");
+  });
+
+  test("the reverse is part of what the gate binds", () => {
+    const subject = (reverse?: string) =>
+      migrationPlanSubject(observation({ state: "migrate", source: { attnum: 2, name: "age_text", type: "text", notNull: false, generated: false, identity: false }, ...(reverse ? { reverse } : {}) }));
+    expect(subject("CAST(age AS text)")).toMatchObject({ reverse: "CAST(age AS text)" });
+    expect(subject()).not.toHaveProperty("reverse");
+  });
+});
+
+describe("the contract of a rename that kept its default", () => {
+  const sequence = { kind: "serial", schema: "app", name: "users_seq_seq", ident: "app.users_seq_seq" } as const;
+
+  test("a plain default is set on the new column in the contract's transaction, after the old column goes", () => {
+    const o = observation({ column: { name: "login", type: "text", default: "'none'" } });
+    expect(contractStatements(o)).toEqual([
+      "DROP TRIGGER login__chant_sync ON app.users",
+      "DROP FUNCTION app.users__login__chant_sync()",
+      "ALTER TABLE app.users DROP COLUMN email",
+      "ALTER TABLE app.users ALTER COLUMN login SET DEFAULT 'none'",
+    ]);
+  });
+
+  test("a serial's sequence is handed to the new column before the old one is dropped, and stays its default", () => {
+    const o = observation({
+      column: { name: "login", type: "serial" },
+      old: { attnum: 2, name: "email", type: "integer", notNull: true, default: "nextval('app.users_seq_seq'::regclass)", generated: false, identity: false },
+      sequence,
+    });
+    expect(contractStatements(o)).toEqual([
+      "DROP TRIGGER login__chant_sync ON app.users",
+      "DROP FUNCTION app.users__login__chant_sync()",
+      "ALTER SEQUENCE app.users_seq_seq OWNED BY app.users.login",
+      "ALTER TABLE app.users DROP COLUMN email",
+      "ALTER TABLE app.users ALTER COLUMN login SET DEFAULT nextval('app.users_seq_seq'::regclass)",
+    ]);
+  });
+
+  test("an identity moves to the new column under its sequence's name and carries on where the old one stood", () => {
+    const o = observation({
+      column: { name: "login", type: "integer", generated: { kind: "identity", always: true, options: "(CACHE 5)" } },
+      old: { attnum: 2, name: "email", type: "integer", notNull: true, generated: false, identity: true },
+      sequence: { ...sequence, kind: "identity" },
+    });
+    expect(contractStatements(o, { lastValue: "41", isCalled: true })).toEqual([
+      "DROP TRIGGER login__chant_sync ON app.users",
+      "DROP FUNCTION app.users__login__chant_sync()",
+      "ALTER TABLE app.users ALTER COLUMN email DROP IDENTITY",
+      "ALTER TABLE app.users DROP COLUMN email",
+      "ALTER TABLE app.users ALTER COLUMN login ADD GENERATED ALWAYS AS IDENTITY (SEQUENCE NAME app.users_seq_seq CACHE 5)",
+      "SELECT pg_catalog.setval('app.users_seq_seq', 41, true)",
+    ]);
+    expect(() => contractStatements(o)).toThrow(/needs its sequence's state/);
+  });
+
+  test("a rename without a default drops the old column and nothing else, as before", () => {
+    expect(contractStatements(observation())).toEqual([
+      "DROP TRIGGER login__chant_sync ON app.users",
+      "DROP FUNCTION app.users__login__chant_sync()",
+      "ALTER TABLE app.users DROP COLUMN email",
+    ]);
+  });
+
+  test("a type change's contract is the plain drop: its trigger went at the switch", () => {
+    const t = migrationNames("app", "orders", "amount", "type", "amount");
+    const o = observation({
+      names: t,
+      old: { attnum: 3, name: t.oldColumn, type: "text", notNull: false, generated: false, identity: false },
+      column: { name: "amount", type: "numeric", default: "0" },
+    });
+    delete (o as { trigger?: unknown }).trigger;
+    delete (o as { fn?: unknown }).fn;
+    expect(contractStatements(o)).toEqual(["ALTER TABLE app.orders DROP COLUMN amount__chant_old"]);
+  });
+});
+
+describe("what the Op still refuses", () => {
+  const rel: RelationRow = { oid: "16384", kind: "r", partition: false, parents: null, children: null, partkey: null, partattrs: null };
+  const source = (over: Partial<ServerColumn> = {}): ServerColumn => ({ attnum: 2, name: "email", type: "text", notNull: false, generated: false, identity: false, ...over });
+  const rename = { rule: "SQLPG205", object: "app.users", field: "columns.login", before: "email", after: "login" } as PgChange;
+  const retype = { rule: "SQLPG208", object: "app.users", field: "columns.login.type", before: "text", after: "integer" } as PgChange;
+  // Every query answers nothing, except the primary key's.
+  const client = { query: async (sql: string) => (sql.includes("contype = 'p'") ? [{ name: "id", type: "bigint" }] : []) } as unknown as PostgresClient;
+  const run = (extra: { reverse?: string; defaultAtContract?: boolean }, src: ServerColumn, column: { name: string; type: string; default?: string }, changes: PgChange[], isRename = true) =>
+    refuseUnsupported(
+      { client, target: { defaultSchema: "app" }, declared: { props: {}, canonical: { schema: "app", name: "users" } }, column: "login", ...extra } as never,
+      names,
+      rel,
+      src,
+      column as never,
+      changes,
+      isRename,
+      changes.find((c) => c.rule !== "SQLPG205"),
+    );
+
+  test("a rename with a type change names reverse, and goes on with it", async () => {
+    await expect(run({}, source(), { name: "login", type: "integer" }, [rename, retype])).rejects.toThrow(/give that expression as reverse/);
+    await expect(run({ reverse: "CAST(login AS text)" }, source(), { name: "login", type: "integer" }, [rename, retype])).resolves.toMatchObject({ batchKey: "id" });
+  });
+
+  test("reverse is refused where nothing needs it, and may not carry the function's quote", async () => {
+    await expect(run({ reverse: "x" }, source(), { name: "login", type: "text" }, [rename])).rejects.toThrow(/reverse is for a rename combined with a type change, and this migration is a rename only/);
+    await expect(run({ reverse: "x" }, source(), { name: "login", type: "integer" }, [retype], false)).rejects.toThrow(/a type change without a rename/);
+    await expect(run({ reverse: "$chant$" }, source(), { name: "login", type: "integer" }, [rename, retype])).rejects.toThrow(/may not contain \$chant\$/);
+  });
+
+  test("a rename with a type change and a default or identity is refused whatever is set", async () => {
+    const msg = /also changes its type[\s\S]*Rename first/;
+    await expect(run({ reverse: "x", defaultAtContract: true }, source({ default: "'a'::text" }), { name: "login", type: "integer" }, [rename, retype])).rejects.toThrow(msg);
+    await expect(run({ reverse: "x", defaultAtContract: true }, source({ identity: true }), { name: "login", type: "integer" }, [rename, retype])).rejects.toThrow(msg);
+  });
+
+  test("a rename of a column with a default needs defaultAtContract, and says what it gives up", async () => {
+    const withDefault = source({ default: "'none'::text" });
+    const refused = run({}, withDefault, { name: "login", type: "text", default: "'none'" }, [rename]);
+    await expect(refused).rejects.toThrow(/Set defaultAtContract: true/);
+    await expect(run({}, withDefault, { name: "login", type: "text", default: "'none'" }, [rename])).rejects.toThrow(/explicit NULL gets the default, and UPDATE \.\.\. SET <new> = DEFAULT sets NULL/);
+    await expect(run({}, source({ identity: true }), { name: "login", type: "integer" }, [rename])).rejects.toThrow(/Set defaultAtContract: true/);
+    await expect(run({ defaultAtContract: true }, withDefault, { name: "login", type: "text", default: "'none'" }, [rename])).resolves.toMatchObject({ batchKey: "id" });
+  });
+
+  test("defaultAtContract is refused on a rename that has no default to wait for", async () => {
+    await expect(run({ defaultAtContract: true }, source(), { name: "login", type: "text" }, [rename])).rejects.toThrow(/defaultAtContract is for a rename of a column with a default/);
+  });
+});
+
+describe("the Op's configuration", () => {
+  test("reverse and defaultAtContract reach every step, and the steps still pass the activity contracts", async () => {
+    const config: PostgresMigrationOpConfig = { ...BASE, using: "CAST(age_text AS integer)", reverse: "CAST(age AS text)", defaultAtContract: true };
+    const props = propsOf(config);
+    const steps = props.phases.flatMap((p) => p.steps).filter((s) => s.kind === "activity" && (s as { fn: string }).fn.startsWith("postgresMigration")) as Array<{ args: Record<string, unknown> }>;
+    expect(steps).toHaveLength(9);
+    for (const s of steps) expect(s.args).toMatchObject({ reverse: "CAST(age AS text)", defaultAtContract: true });
+    const contracts = new Map<string, ActivityContract>();
+    collectActivityContracts(contractsModule as unknown as Record<string, unknown>, contracts);
+    expect(validateActivitySteps(props, mergeActivityContracts(await loadActivityContracts([]), contracts))).toEqual([]);
+    for (const s of propsOf(BASE).phases.flatMap((p) => p.steps)) if (s.kind === "activity") expect((s as { args?: Record<string, unknown> }).args ?? {}).not.toHaveProperty("defaultAtContract");
+  });
+});

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

@@ -10,7 +10,7 @@
  * - A column of a partitioned table: every partition follows the
  *   partitioned table.
  * - Refused, each naming why: a partition, an inheritance tree, a column in
- *   the partition key, an index on a partitioned table, a generated column,
+ *   the partition key, a key on a partitioned table, a generated column,
  *   a rename of an identity column.
  *
  * Needs Docker; skips cleanly without it.
@@ -177,7 +177,7 @@ describe.skipIf(!enabled)("what the Op refuses among the rest", () => {
       (e: unknown) => String((e as Error).message),
     );
 
-  test("a partition, an inheritance tree, the partition key, an index on a partitioned table, a generated column, a renamed identity", async () => {
+  test("a partition, an inheritance tree, the partition key, a key on a partitioned table, a generated column, a renamed identity", async () => {
     const parted = (v: string, key = "at") => table("parted", "rf", `CREATE TABLE rf.parted (id bigint, at date, v ${v}, PRIMARY KEY (id, at)) PARTITION BY RANGE (${key})`);
     const p1 = table("parted1", "rf", "CREATE TABLE rf.parted1 PARTITION OF rf.parted FOR VALUES FROM ('2025-01-01') TO ('2026-01-01')", ["parted"]);
     const parent = (v: string) => table("parent", "rf", `CREATE TABLE rf.parent (id bigint PRIMARY KEY, v ${v})`);
@@ -185,16 +185,16 @@ describe.skipIf(!enabled)("what the Op refuses among the rest", () => {
     const ident = (c: string, hint = "") => table("ident", "rf", `CREATE TABLE rf.ident (\n  ${c} integer GENERATED ALWAYS AS IDENTITY PRIMARY KEY,${hint}\n  v text\n)`);
     await apply(writeBuild("rf-v1.json", [RF, parted("integer"), p1, parent("integer"), gen("integer"), ident("id")]));
     await admin!.query("CREATE TABLE rf.child (extra text) INHERITS (rf.parent)");
-    await admin!.query("CREATE INDEX parted_v_idx ON rf.parted (v)");
+    await admin!.query("ALTER TABLE rf.parted ADD CONSTRAINT parted_v_key UNIQUE (id, at, v)");
     writeBuild("rf-v2.json", [RF, parted("bigint"), p1, parent("bigint"), gen("bigint"), ident("key", " -- previously: id")]);
 
     expect(await refusal("rf.parted1", "v", "rf-v2.json")).toMatch(/^rf\.parted1 is a partition of rf\.parted\. A partition's columns are its partitioned table's: run the Op on rf\.parted/);
     expect(await refusal("rf.parent", "v", "rf-v2.json")).toMatch(/^rf\.parent has inheritance children \(rf\.child\)\. The Op does not migrate inheritance trees: a write to a child table does not fire the parent's dual-write trigger/);
-    expect(await refusal("rf.parted", "v", "rf-v2.json")).toMatch(/index rf\.parted_v_idx is a partitioned index, which cannot be built CONCURRENTLY/);
+    expect(await refusal("rf.parted", "v", "rf-v2.json")).toMatch(/unique constraint parted_v_key on rf\.parted: on a partitioned table a key cannot be attached from an index built CONCURRENTLY/);
     expect(await refusal("rf.gen", "g", "rf-v2.json")).toMatch(/^rf\.gen\.g is a generated column\. There is no expand and contract for one/);
     expect(await refusal("rf.ident", "key", "rf-v2.json")).toMatch(/sequence rf\.ident_id_seq gives the column its values \(an identity column\); during a rename/);
 
-    await admin!.query("DROP INDEX rf.parted_v_idx");
+    await admin!.query("ALTER TABLE rf.parted DROP CONSTRAINT parted_v_key");
     writeBuild("rf-v3.json", [RF, parted("integer", "v"), p1]);
     await admin!.query("DROP TABLE rf.parted");
     await apply(writeBuild("rf-v3.json", [RF, table("parted", "rf", "CREATE TABLE rf.parted (id bigint, at date, v integer, PRIMARY KEY (id, v)) PARTITION BY RANGE (v)")]));