@intentius/chant-lexicon-sql 0.124.46 → 0.124.49

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/)]);
+  });
+});

package/src/postgres/migrate/replication.ts

@@ -34,6 +34,32 @@
  * publication sends the migrated column of, naming each publication. A
  * publication with a column list (15 and later) that leaves the column out
  * sends neither it nor the new one, and does not stop the migration.
+ *
+ * ## Subscriptions (#4405)
+ *
+ * The other side: a table that is the target of a subscription. The
+ * subscription's apply worker runs with `session_replication_role = replica`
+ * ("Logical Replication", Architecture,
+ * https://www.postgresql.org/docs/18/logical-replication-architecture.html),
+ * and a trigger made by plain `CREATE TRIGGER` is `ENABLE ORIGIN`: it fires
+ * only while the setting is `origin` or `local`
+ * (https://www.postgresql.org/docs/18/runtime-config-client.html#GUC-SESSION-REPLICATION-ROLE).
+ * Only `ENABLE REPLICA` and `ENABLE ALWAYS` triggers fire for the worker
+ * (https://www.postgresql.org/docs/18/sql-altertable.html, the TRIGGER
+ * clauses). The architecture page says "by default, triggers and rules will
+ * not fire on a subscriber" and points to `ENABLE TRIGGER` to change it. So the dual write
+ * never sees a replicated row, and the new column goes stale. The initial
+ * table copy is the exception: it is a `COPY` and fires plain triggers.
+ *
+ * `ENABLE ALWAYS` would make the trigger fire, and the Plan phase refuses
+ * the table instead, because the Op's later steps assume it controls every
+ * writer of the old column. The publisher keeps sending the old column's name
+ * and the subscriber applies by name, so a rename's contract (which drops the
+ * old column) would stop the apply at the next row, and the switch of a
+ * type change would change the column under a running apply worker. Neither
+ * order can be made inside this Op's one connection to one server; that is
+ * the same limit #3332 recorded for the publisher side. The refusal names
+ * each subscription.
  */
 
 import type { PostgresClient } from "../live/client";
@@ -149,3 +175,43 @@ function sleepFor(ms: number, signal?: AbortSignal): Promise<void> {
     );
   });
 }
+
+/** One subscription that has the table, or a partition of it, as a target. */
+export interface SubscriptionHit {
+  name: string;
+  enabled: boolean;
+}
+
+/**
+ * The subscriptions of the current database with a row in `pg_subscription_rel`
+ * for `schema.table` (and, on a partitioned table, for any of its
+ * partitions, which is where a subscription to a partitioned table lists the
+ * tables it applies to). Read at plan time; `pg_subscription_rel` is
+ * per database and `pg_subscription` is shared, so the join keeps this
+ * database's rows (`subdbid`).
+ */
+export async function subscriptionsOf(client: Pick<PostgresClient, "query">, schema: string, table: string, major: number): Promise<SubscriptionHit[]> {
+  const rel = "pg_catalog.to_regclass(pg_catalog.quote_ident($1) || '.' || pg_catalog.quote_ident($2))";
+  const tables = major >= 12 ? `SELECT relid FROM pg_catalog.pg_partition_tree(${rel})` : `SELECT ${rel}::oid AS relid`;
+  const rows = await client.query<{ subname: string; subenabled: boolean }>(
+    `SELECT DISTINCT s.subname, s.subenabled
+     FROM pg_catalog.pg_subscription_rel sr
+     JOIN pg_catalog.pg_subscription s ON s.oid = sr.srsubid
+     WHERE s.subdbid = (SELECT oid FROM pg_catalog.pg_database WHERE datname = pg_catalog.current_database())
+       AND sr.srrelid IN (${tables})
+     ORDER BY s.subname`,
+    [schema, table],
+  );
+  return rows.map((r) => ({ name: r.subname, enabled: r.subenabled }));
+}
+
+/** The Plan phase's refusal for a table that a subscription applies to. */
+export function subscriptionRefusal(where: string, column: string, hits: SubscriptionHit[]): string {
+  return (
+    `${where} is a target of logical replication subscription(s) ${hits.map((h) => `${h.name}${h.enabled ? "" : " (disabled)"}`).join(", ")}. ` +
+    `A subscription's apply worker runs with session_replication_role = replica, where a trigger made by CREATE TRIGGER does not fire, so the dual write would never see a replicated row and the new column of ${column} would go stale ` +
+    `(https://www.postgresql.org/docs/18/runtime-config-client.html#GUC-SESSION-REPLICATION-ROLE). ` +
+    `ENABLE ALWAYS would fire it, but the publisher keeps sending the old column's name and the subscriber applies by name, so the contract (or the switch of a type change) would stop the apply, and one Op cannot change both servers. ` +
+    `Take the table out of the subscription (drop it from the publication and ALTER SUBSCRIPTION ... REFRESH PUBLICATION), or migrate the publisher and the subscriber by hand. A migration of both together is chant #3332.`
+  );
+}