@intentius/chant-lexicon-sql 0.0.0-stage → 0.112.0

package/src/postgres/migrate/op.ts

@@ -0,0 +1,242 @@
+/**
+ * `PostgresMigrationOp` (#3281): the column change Postgres cannot make in
+ * place without breaking readers (a rename, SQLPG205; a type change across
+ * kinds, SQLPG208), run as expand and contract in a gated composite Op. A
+ * type change within a kind that rewrites the table under ACCESS EXCLUSIVE
+ * (SQLPG207) can run as the same Op, which fills the new column in batches
+ * instead.
+ *
+ *     export const { op } = PostgresMigrationOp({
+ *       name: "migrate-app-users-login",
+ *       env: "prod",
+ *       table: "app.users",
+ *       column: "login",
+ *     });
+ *
+ * | Phase | Step |
+ * |---|---|
+ * | Build | `chant build` (`build: false` skips it) |
+ * | Plan | classify the column's change against the server; refuse what the Op does not make |
+ * | 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`) |
+ * | 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 |
+ * | Retain | the old column, until `retain` has passed |
+ * | Approve contract | a gate bound to that old column |
+ * | Contract | drop the old column (and a rename's trigger) once its date has passed |
+ * | onFailure | drop what the expand added: the trigger, its function, the check, the new column, the receipts |
+ *
+ * Run it until it is done: each run goes as far as the next gate. Every step
+ * re-reads the server, so a run after a gate, a crash or an approval picks up
+ * where the last stopped. A run killed during the backfill (Ctrl-C, a lost
+ * machine) is not a failure, runs no onFailure, and the next run resumes the
+ * backfill from its receipts; a step that fails runs onFailure, and the next
+ * run starts again from a new column.
+ */
+
+import { Op, activity, gate, phase, stepOutput, type GateApproval } from "@intentius/chant/op";
+import type { OpResource } from "@intentius/chant/op";
+import type { StepDefinition } from "@intentius/chant/op";
+import { parseDuration } from "@intentius/chant/op";
+
+export interface PostgresMigrationOpConfig {
+  /** Op name (kebab-case). */
+  name: string;
+  /** The chant environment: selects `sql.profiles.<env>`. */
+  env: string;
+  /** The table, `schema.name` as the server knows it (or its export name). */
+  table: string;
+  /** The column as the build declares it: the new name for a rename. */
+  column: string;
+  /**
+   * A type change: the SQL expression that computes the new value from the
+   * old row's columns, as `ALTER COLUMN ... TYPE ... USING` takes it. Default:
+   * `CAST(<column> AS <declared type>)`. The backfill, the dual-write trigger
+   * and the verification all use it.
+   */
+  using?: string;
+  /** The build output the declaration is read from. Default: `dist/schema.json`. */
+  output?: string;
+  /** Project directory to build. Default: `.`. */
+  path?: string;
+  /** Run `chant build` first (the project's `build` script). Default: true. */
+  build?: boolean;
+  /** How long the old column is kept after the switch, as a duration (`7d`, `36h`). Default: `7d`. */
+  retain?: string;
+  /**
+   * Rows per batch: the width of a batch's range of a primary key of one
+   * integer column, or how many keys lie between two recorded boundaries of
+   * any other key (uuid, text, several columns). Default: 1000.
+   */
+  batchSize?: number;
+  /**
+   * Pause the backfill while a replica's replay lag is above `max`, for up to
+   * `wait` at a time. Default: `{ max: "10s", wait: "30m" }`. `false` turns
+   * the check off.
+   */
+  replicationLag?: { max?: string; wait?: string } | false;
+  /** `lock_timeout` for every statement, in ms. Default: the profile's `lockTimeoutMs`, else 5000. */
+  lockTimeoutMs?: number;
+  /** `statement_timeout` for every statement but the scans (validation, verification), in ms. Default: the profile's `statementTimeoutMs`, else 60000. */
+  statementTimeoutMs?: number;
+  /** The gate before the switch. Default name `approve-<name>`. */
+  gate?: {
+    gate?: string;
+    timeout?: string;
+    description?: string;
+    /** Quorum, roles and a policy (#2508). With a policy, the verification's counts are added to its context. */
+    approval?: GateApproval;
+  };
+  /** The gate before the old column is dropped. Default name `approve-<name>-contract`. */
+  contractGate?: { gate?: string; timeout?: string; description?: string };
+  /** One attempt of the backfill step. Default: `6h`, the longest a step may run. */
+  backfillTimeout?: string;
+  /** Ownership stack. Default: `ownership.stack` in `chant.config.ts`. */
+  stack?: string;
+  /** Ownership env. Default: `ownership.env` in `chant.config.ts`. */
+  ownershipEnv?: string;
+}
+
+export interface PostgresMigrationOpResources {
+  op: InstanceType<typeof OpResource>;
+}
+
+/** The arguments every migration activity takes. */
+export interface PostgresMigrationArgs {
+  table: string;
+  column: string;
+  buildPath: string;
+  environment?: string;
+  using?: string;
+  retain?: string;
+  batchSize?: number;
+  replicationLag?: { max?: string; wait?: string } | false;
+  lockTimeoutMs?: number;
+  statementTimeoutMs?: number;
+  stack?: string;
+  ownershipEnv?: string;
+  cwd?: string;
+}
+
+const IDENT = /^[A-Za-z_][A-Za-z0-9_$]*$|^"(?:[^"]|"")+"$/;
+
+export function PostgresMigrationOp(config: PostgresMigrationOpConfig): PostgresMigrationOpResources {
+  const parts = config.table.split(".");
+  if (parts.length > 2 || !parts.every((p) => /^[A-Za-z_][A-Za-z0-9_$]*$/.test(p))) {
+    throw new Error(`PostgresMigrationOp "${config.name}": table must be "schema.name" or an export name, got ${JSON.stringify(config.table)}`);
+  }
+  if (!config.column || !IDENT.test(config.column)) throw new Error(`PostgresMigrationOp "${config.name}": column must be the declared column's name, got ${JSON.stringify(config.column)}`);
+  if (config.batchSize !== undefined && (!Number.isInteger(config.batchSize) || config.batchSize < 1)) {
+    throw new Error(`PostgresMigrationOp "${config.name}": batchSize must be a positive integer, got ${config.batchSize}`);
+  }
+  if (config.replicationLag) for (const d of [config.replicationLag.max, config.replicationLag.wait]) if (d !== undefined) parseDuration(d);
+  if (config.retain !== undefined) parseDuration(config.retain);
+
+  const args: PostgresMigrationArgs = {
+    table: config.table,
+    column: config.column,
+    buildPath: config.output ?? "dist/schema.json",
+    environment: config.env,
+    ...(config.using !== undefined ? { using: config.using } : {}),
+    ...(config.retain ? { retain: config.retain } : {}),
+    ...(config.batchSize !== undefined ? { batchSize: config.batchSize } : {}),
+    ...(config.replicationLag !== undefined ? { replicationLag: config.replicationLag } : {}),
+    ...(config.lockTimeoutMs !== undefined ? { lockTimeoutMs: config.lockTimeoutMs } : {}),
+    ...(config.statementTimeoutMs !== undefined ? { statementTimeoutMs: config.statementTimeoutMs } : {}),
+    ...(config.stack ? { stack: config.stack } : {}),
+    ...(config.ownershipEnv ? { ownershipEnv: config.ownershipEnv } : {}),
+    ...(config.path && config.path !== "." ? { cwd: config.path } : {}),
+  };
+  const a = args as unknown as Record<string, unknown>;
+  const switchGate = config.gate?.gate ?? `approve-${config.name}`;
+  const contractGate = config.contractGate?.gate ?? `approve-${config.name}-contract`;
+  const policy = config.gate?.approval?.policy;
+  const what = `${config.table}.${config.column}`;
+
+  const step = (fn: string, extra: Partial<StepDefinition & { id: string; outcomeAttribute: unknown; profile: string; timeout: string }> = {}): StepDefinition =>
+    ({ ...activity(fn, a), ...extra }) as StepDefinition;
+
+  const phases = [
+    ...(config.build === false ? [] : [phase("Build", [activity("chantBuild", { path: config.path ?? "." })])]),
+    phase("Plan", [step("postgresMigrationPlan", { id: "plan", outcomeAttribute: [{ name: "MigrationState", from: "state" }, { name: "Change", from: "change" }] })]),
+    phase("Expand", [step("postgresMigrationExpand")]),
+    phase("Dual write", [step("postgresMigrationDualWrite")]),
+    phase("Backfill", [
+      step("postgresMigrationBackfill", {
+        profile: "fastIdempotent",
+        timeout: config.backfillTimeout ?? "6h",
+        outcomeAttribute: [
+          { name: "Filled", from: "filled" },
+          { name: "Skipped", from: "skipped" },
+          { name: "BackfilledRows", from: "rows" },
+        ],
+      }),
+    ]),
+    phase("Carry over", [
+      step("postgresMigrationCarry", {
+        timeout: "6h",
+        outcomeAttribute: [
+          { name: "Carried", from: "carried" },
+          { name: "CarriedBuilt", from: "built" },
+        ],
+      }),
+    ]),
+    phase("Verify", [
+      step("postgresMigrationVerify", {
+        id: "verify",
+        timeout: "6h",
+        outcomeAttribute: [
+          { name: "Verification", from: "summary" },
+          { name: "VerifiedRows", from: "rows" },
+        ],
+      }),
+    ]),
+    phase("Approve", [
+      gate(switchGate, {
+        ...(config.gate?.timeout ? { timeout: config.gate.timeout } : {}),
+        plan: stepOutput("verify", "planDigest"),
+        description:
+          config.gate?.description ??
+          `Approve switching ${what} on ${config.env}: the run record's Verification line has what this approval binds; for a rename, readers move to the new name once it is switched`,
+        ...(config.gate?.approval
+          ? {
+              approval: {
+                ...config.gate.approval,
+                ...(policy
+                  ? {
+                      context: {
+                        verifiedRows: stepOutput("verify", "rows"),
+                        mismatched: stepOutput("verify", "mismatched"),
+                        ...config.gate.approval.context,
+                      },
+                    }
+                  : {}),
+              },
+            }
+          : {}),
+      }),
+    ]),
+    phase("Switch", [step("postgresMigrationSwitch", { timeout: "6h", outcomeAttribute: [{ name: "OldColumn", from: "oldColumn" }] })]),
+    phase("Retain", [step("postgresMigrationRetain", { id: "retain", outcomeAttribute: { name: "RetainUntil", from: "retainUntil" } })]),
+    phase("Approve contract", [
+      gate(contractGate, {
+        ...(config.contractGate?.timeout ? { timeout: config.contractGate.timeout } : {}),
+        plan: stepOutput("retain", "contractDigest"),
+        description: config.contractGate?.description ?? `Approve dropping the old column of ${what} once its retention has passed and no reader uses it`,
+      }),
+    ]),
+    phase("Contract", [step("postgresMigrationContract", { outcomeAttribute: { name: "Dropped", from: "dropped" } })]),
+  ];
+
+  const op = Op({
+    name: config.name,
+    overview: `Migrate ${what} on ${config.env} as expand and contract: new column, dual write, backfill, verify, gated switch, gated contract`,
+    labels: { Migration: "true", Env: config.env, Table: config.table, Column: config.column },
+    phases,
+    onFailure: [phase("Compensate", [step("postgresMigrationCompensate")])],
+  });
+  return { op };
+}

package/src/postgres/migrate/receipts.ts

@@ -0,0 +1,135 @@
+/**
+ * Effect receipts kept in Postgres (#3281): where the expand-and-contract
+ * migration's backfill records which batches it has filled.
+ *
+ * A receipt is the proof that one effect ran, kept where the effect happened
+ * (concepts/effect-receipts.mdx). A batch's effect is "these rows of the
+ * table have the new column filled", so the receipt is a row in the same
+ * database, in the table's own schema:
+ *
+ *     SELECT * FROM app.__chant_receipts
+ *
+ * In the table's schema rather than a `chant_receipts` schema, as #3265 put
+ * the ClickHouse receipts of a Replicated database beside the tables they
+ * witness: whoever can read the table can read its receipts, and a
+ * provider that reserves schemas or limits `CREATE SCHEMA` (#3282) does not
+ * stop the migration. The table's comment carries chant's trailer with the
+ * `receipts` key, so the catalog read leaves it out of plans, import and
+ * prune.
+ *
+ * Postgres adds what ClickHouse could not: the receipt is written in the
+ * batch's own transaction, after its `UPDATE`, and commits with it. The
+ * receipt is still written last and on success only, and a run killed
+ * anywhere leaves either the batch and its receipt or neither, so a resumed
+ * backfill never updates a batch twice. Each expectation is bound to the
+ * table's oid and the new column's attribute number, which a column dropped
+ * by onFailure and added again does not keep, so an old receipt reads as
+ * stale; onFailure and the contract also delete the migration's receipts.
+ *
+ * The store implements the shared core's `SqlReceiptStore`
+ * (`../../core/receipts.ts`) over the migration's own connection. It is not
+ * exported as the `receiptRead` / `receiptWrite` activities, whose names are
+ * global to a run and belong to an aws or k8s project's receipt row.
+ */
+
+import { OWNERSHIP_MANAGED_BY_VALUE } from "@intentius/chant/ownership";
+import type { EffectReceiptRef } from "@intentius/chant/op/receipt-store";
+import { COMMENT_OWNERSHIP_KEYS, hasChantTrailerKey, RECEIPTS_TRAILER_KEY } from "../../core/ownership";
+import { receiptAddress, type SqlReceiptStore } from "../../core/receipts";
+import { quoteIdent } from "../keywords";
+import type { PostgresClient } from "../live/client";
+
+/** The receipts table, in the migrated table's schema. */
+export const POSTGRES_RECEIPTS_TABLE = "__chant_receipts";
+
+const COMMENT = `chant effect receipts [chant ${COMMENT_OWNERSHIP_KEYS.managedBy}=${OWNERSHIP_MANAGED_BY_VALUE} ${RECEIPTS_TRAILER_KEY}=effects]`;
+
+export { receiptAddress } from "../../core/receipts";
+
+/** A receipts table chant did not make: a user's table under the same name. */
+export class ReceiptsTableConflict extends Error {
+  constructor(schema: string) {
+    super(
+      `${schema}.${POSTGRES_RECEIPTS_TABLE} exists and is not chant's receipts table (its comment carries no receipts marker). ` +
+        `The migration keeps its receipts under that name, so it stops rather than write into it; rename the table.`,
+    );
+    this.name = "ReceiptsTableConflict";
+  }
+}
+
+export interface PostgresReceiptStore extends SqlReceiptStore {
+  /** The qualified, quoted table name. */
+  table: string;
+  /** Create the table if it is not there. Outside any transaction the store's caller has open. */
+  ensure(): Promise<void>;
+  /** Delete every receipt whose address starts with `prefix`, and the table once it holds none. */
+  forget(prefix: string): Promise<number>;
+}
+
+/**
+ * A receipt store in `<schema>.__chant_receipts`, over `client`. `write` runs
+ * on the client as it is, so a write inside the caller's transaction commits
+ * or rolls back with it. `identity` is the project's ownership stack and env,
+ * which every address starts with.
+ */
+export function postgresReceiptStore(client: PostgresClient, schema: string, identity: { stack?: string; env?: string }, opts: { runId?: string } = {}): PostgresReceiptStore {
+  const table = `${quoteIdent(schema)}.${quoteIdent(POSTGRES_RECEIPTS_TABLE)}`;
+  let ensured = false;
+  const comment = async (): Promise<string | null | undefined> => {
+    const [row] = await client.query<{ present: boolean; comment: string | null }>(
+      "SELECT pg_catalog.to_regclass($1) IS NOT NULL AS present, pg_catalog.obj_description(pg_catalog.to_regclass($1), 'pg_class') AS comment",
+      [table],
+    );
+    return row?.present ? (row.comment ?? null) : undefined;
+  };
+  /** Whether there is a table to read; one that is not chant's is refused. */
+  const readable = async (): Promise<boolean> => {
+    if (ensured) return true;
+    const c = await comment();
+    if (c === undefined) return false;
+    if (!hasChantTrailerKey(c ?? undefined, [RECEIPTS_TRAILER_KEY])) throw new ReceiptsTableConflict(schema);
+    return true;
+  };
+  const address = (receipt: EffectReceiptRef) => receiptAddress(identity, receipt.effect);
+
+  return {
+    table,
+    async ensure() {
+      if (ensured) return;
+      if (!(await readable())) {
+        await client.query(
+          `CREATE TABLE IF NOT EXISTS ${table} (address text PRIMARY KEY, effect text NOT NULL, expectation text NOT NULL, run_id text NOT NULL DEFAULT '', written_at timestamptz NOT NULL DEFAULT pg_catalog.now())`,
+        );
+        await client.query(`COMMENT ON TABLE ${table} IS '${COMMENT.replace(/'/g, "''")}'`);
+      }
+      ensured = true;
+    },
+    async read(receipt) {
+      if (!(await readable())) return undefined;
+      const [row] = await client.query<{ expectation: string }>(`SELECT expectation FROM ${table} WHERE address = $1`, [address(receipt)]);
+      return row?.expectation;
+    },
+    async readAll(prefix) {
+      if (!(await readable())) return new Map();
+      const rows = await client.query<{ address: string; expectation: string }>(`SELECT address, expectation FROM ${table} WHERE starts_with(address, $1)`, [prefix]);
+      return new Map(rows.map((r) => [r.address, r.expectation]));
+    },
+    async write(receipt, expectation) {
+      await client.query(
+        `INSERT INTO ${table} (address, effect, expectation, run_id) VALUES ($1, $2, $3, $4) ` +
+          "ON CONFLICT (address) DO UPDATE SET effect = EXCLUDED.effect, expectation = EXCLUDED.expectation, run_id = EXCLUDED.run_id, written_at = pg_catalog.now()",
+        [address(receipt), receipt.effect, expectation, opts.runId ?? ""],
+      );
+    },
+    async forget(prefix) {
+      if (!(await readable())) return 0;
+      const deleted = await client.query<{ address: string }>(`DELETE FROM ${table} WHERE starts_with(address, $1) RETURNING address`, [prefix]);
+      const [left] = await client.query<{ n: number }>(`SELECT count(*)::int AS n FROM ${table}`);
+      if (left?.n === 0) {
+        await client.query(`DROP TABLE IF EXISTS ${table}`);
+        ensured = false;
+      }
+      return deleted.length;
+    },
+  };
+}

package/src/postgres/migrate/replication.ts

@@ -0,0 +1,151 @@
+/**
+ * Replication around an expand-and-contract migration (#3281): the backfill
+ * pauses while a replica is behind, and a table that logical replication
+ * publishes is refused.
+ *
+ * ## Lag
+ *
+ * A backfill writes every row of the table once more, and each batch's WAL
+ * goes to every standby and every logical subscriber. Before each batch the
+ * backfill reads `pg_stat_replication` on the primary
+ * (https://www.postgresql.org/docs/18/monitoring-stats.html#MONITORING-PG-STAT-REPLICATION-VIEW),
+ * one row per WAL sender, and waits while any `replay_lag` is above the
+ * bound, up to a deadline, then stops naming the replica. `replay_lag` is
+ * NULL once a standby has caught up and nothing new is being sent, which is
+ * no lag. No rows means no replicas, and the check passes at once: a single
+ * server, or a managed one whose replicas are not WAL senders (Aurora's
+ * share storage), skips cleanly.
+ *
+ * A role that is neither superuser nor a member of `pg_monitor` sees the
+ * rows with every column but the process's own NULL, so the lag cannot be
+ * read; that stops the backfill with the grant to make, rather than go on
+ * blind. `replicationLag: false` on the Op turns the check off.
+ *
+ * ## Publications
+ *
+ * A logical replication subscriber applies each published row change by
+ * column name, and its own table must have every column the publisher
+ * sends ("Logical Replication", Restrictions and Column Lists,
+ * https://www.postgresql.org/docs/18/logical-replication-col-lists.html).
+ * The expand adds a column, so a publication that sends the whole table
+ * would fail the subscriber's apply at the first backfilled row, and a
+ * rename or a type change would need the same change on the subscriber at
+ * the same moment as the switch. The Plan phase therefore refuses a table a
+ * 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.
+ */
+
+import type { PostgresClient } from "../live/client";
+
+export interface ReplicationLagBound {
+  /** The most a replica may be behind before a batch waits, in ms. */
+  maxLagMs: number;
+  /** How long one wait may last before the backfill stops, in ms. */
+  waitMs: number;
+}
+
+export const DEFAULT_REPLICATION_LAG: ReplicationLagBound = { maxLagMs: 10_000, waitMs: 30 * 60_000 };
+
+/** A replica that stayed behind past the wait, or whose lag this role cannot read. */
+export class ReplicationLagError extends Error {
+  constructor(message: string) {
+    super(message);
+    this.name = "ReplicationLagError";
+  }
+}
+
+export interface ReplicaLag {
+  /** `application_name`, else the client address, else the process id. */
+  name: string;
+  /** Replay lag in ms; undefined when the role cannot read it. */
+  lagMs?: number;
+}
+
+/** The WAL senders on this server and how far behind each replica's replay is. */
+export async function replicaLags(client: Pick<PostgresClient, "query">): Promise<ReplicaLag[]> {
+  const rows = await client.query<{ name: string; state: string | null; lag_ms: string | number | null }>(
+    `SELECT COALESCE(NULLIF(application_name, ''), client_addr::text, pid::text) AS name, state,
+            (EXTRACT(EPOCH FROM replay_lag) * 1000)::bigint AS lag_ms
+     FROM pg_catalog.pg_stat_replication`,
+  );
+  return rows.map((r) => ({ name: r.name, ...(r.state !== null ? { lagMs: r.lag_ms === null ? 0 : Number(r.lag_ms) } : {}) }));
+}
+
+/**
+ * Wait until every replica is within the bound. Returns how long it waited,
+ * in ms (0 when no replica was behind, or there are none).
+ */
+export async function waitForReplicas(
+  client: Pick<PostgresClient, "query">,
+  bound: ReplicationLagBound,
+  opts: { log?: (line: string) => void; signal?: AbortSignal; sleep?: (ms: number, signal?: AbortSignal) => Promise<void>; now?: () => number } = {},
+): Promise<number> {
+  const now = opts.now ?? Date.now;
+  const sleep = opts.sleep ?? sleepFor;
+  const started = now();
+  for (;;) {
+    opts.signal?.throwIfAborted();
+    const lags = await replicaLags(client);
+    const unreadable = lags.filter((l) => l.lagMs === undefined);
+    if (unreadable.length > 0) {
+      throw new ReplicationLagError(
+        `pg_stat_replication lists ${unreadable.length} replica(s) (${unreadable.map((l) => l.name).join(", ")}) whose lag this role cannot read. ` +
+          `Grant it pg_monitor (GRANT pg_monitor TO <role>) so the backfill can pause while a replica is behind, or set replicationLag: false on the Op to run without the check.`,
+      );
+    }
+    const behind = lags.filter((l) => l.lagMs! > bound.maxLagMs);
+    if (behind.length === 0) return now() - started;
+    const waited = now() - started;
+    const shown = behind.map((l) => `${l.name} ${Math.round(l.lagMs! / 1000)}s`).join(", ");
+    if (waited >= bound.waitMs) {
+      throw new ReplicationLagError(
+        `waited ${Math.round(waited / 1000)}s for replicas to come within ${Math.round(bound.maxLagMs / 1000)}s of the primary and they did not: ${shown} behind. ` +
+          `The backfill stops here; its receipts keep the batches it filled, and the next run goes on from there.`,
+      );
+    }
+    opts.log?.(`-- replicas behind (${shown}); pausing the backfill`);
+    await sleep(Math.min(1_000, bound.waitMs - waited), opts.signal);
+  }
+}
+
+/** One publication that sends the migrated column. */
+export interface PublicationHit {
+  name: string;
+  /** Whether it sends every column (no column list). */
+  allColumns: boolean;
+}
+
+/**
+ * The publications that send `column` of `schema.table`. On 15 and later a
+ * publication with a column list that leaves the column out is not one;
+ * before 15 there are no column lists, and any publication of the table is.
+ */
+export async function publicationsOf(client: Pick<PostgresClient, "query">, schema: string, table: string, column: string, major: number): Promise<PublicationHit[]> {
+  if (major >= 15) {
+    const rows = await client.query<{ pubname: string; attnames: string[] | null; listed: boolean }>(
+      `SELECT pt.pubname, pt.attnames,
+              EXISTS (SELECT 1 FROM pg_catalog.pg_publication p JOIN pg_catalog.pg_publication_rel r ON r.prpubid = p.oid
+                      WHERE p.pubname = pt.pubname AND r.prrelid = pg_catalog.to_regclass(pg_catalog.quote_ident($1) || '.' || pg_catalog.quote_ident($2)) AND r.prattrs IS NOT NULL) AS listed
+       FROM pg_catalog.pg_publication_tables pt WHERE pt.schemaname = $1 AND pt.tablename = $2 ORDER BY pt.pubname`,
+      [schema, table],
+    );
+    return rows.filter((r) => !r.listed || (r.attnames ?? []).includes(column)).map((r) => ({ name: r.pubname, allColumns: !r.listed }));
+  }
+  const rows = await client.query<{ pubname: string }>("SELECT pubname FROM pg_catalog.pg_publication_tables WHERE schemaname = $1 AND tablename = $2 ORDER BY pubname", [schema, table]);
+  return rows.map((r) => ({ name: r.pubname, allColumns: true }));
+}
+
+function sleepFor(ms: number, signal?: AbortSignal): Promise<void> {
+  return new Promise((resolve, reject) => {
+    const t = setTimeout(resolve, ms);
+    signal?.addEventListener(
+      "abort",
+      () => {
+        clearTimeout(t);
+        reject(signal.reason);
+      },
+      { once: true },
+    );
+  });
+}