@intentius/chant-lexicon-sql 0.124.46 → 0.124.49

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)")]));

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.
@@ -48,9 +49,9 @@ import { POSTGRES_ENTITY_TYPES } from "../entity-types";
 import type { ColumnDef } from "../entities";
 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 { publicationsOf, subscriptionRefusal, subscriptionsOf, 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.`,
@@ -395,6 +405,14 @@ export async function observeMigration(input: ObserveInput): Promise<MigrationOb
           `A migration of the publisher and the subscriber together is chant #3332.`,
       );
     }
+    const subscriptions = await subscriptionsOf(client, schema, table, major);
+    if (subscriptions.length > 0) throw new MigrationRefusal(subscriptionRefusal(where, input.column, subscriptions));
+  }
+
+  // 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 {
@@ -419,13 +437,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 +457,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 +513,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 +549,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) } : {}),