@intentius/chant-lexicon-sql 0.124.30 → 0.124.32

package/dist/postgres/migrate/op.js

@@ -0,0 +1,178 @@
+/**
+ * `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.
+ *
+ * `gates: "outer"` (#3687) leaves out both approval gates and the Contract
+ * phase, for a caller that runs the Op under an approval of its own: the run
+ * goes from Plan to Retain, verification included. `onFailure: "keep"`
+ * leaves out the onFailure, so a failed run's next run resumes the backfill
+ * from its receipts instead of starting again.
+ */
+import { Op, activity, gate, phase, stepOutput } from "@intentius/chant/op";
+import { parseDuration } from "@intentius/chant/op";
+const IDENT = /^[A-Za-z_][A-Za-z0-9_$]*$|^"(?:[^"]|"")+"$/;
+export function PostgresMigrationOp(config) {
+    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);
+    if (config.gates !== undefined && config.gates !== "own" && config.gates !== "outer") {
+        throw new Error(`PostgresMigrationOp "${config.name}": gates must be "own" or "outer"`);
+    }
+    if (config.onFailure !== undefined && config.onFailure !== "drop" && config.onFailure !== "keep") {
+        throw new Error(`PostgresMigrationOp "${config.name}": onFailure must be "drop" or "keep"`);
+    }
+    const outer = config.gates === "outer";
+    const keep = config.onFailure === "keep";
+    const args = {
+        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 } : {}),
+        ...(keep ? { keepOnFailure: true } : {}),
+    };
+    const a = args;
+    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, extra = {}) => ({ ...activity(fn, a), ...extra });
+    // The switch waits for this gate, unless the caller holds the approval (`gates: "outer"`).
+    const approve = 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,
+                                },
+                            }
+                            : {}),
+                    },
+                }
+                : {}),
+        }),
+    ]);
+    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" },
+                ],
+            }),
+        ]),
+        ...(outer ? [] : [approve]),
+        phase("Switch", [step("postgresMigrationSwitch", { timeout: "6h", outcomeAttribute: [{ name: "OldColumn", from: "oldColumn" }] })]),
+        phase("Retain", [step("postgresMigrationRetain", { id: "retain", outcomeAttribute: { name: "RetainUntil", from: "retainUntil" } })]),
+        ...(outer
+            ? []
+            : [
+                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, ${outer ? "switch under the caller's approval" : "gated switch, gated contract"}`,
+        labels: { Migration: "true", Env: config.env, Table: config.table, Column: config.column },
+        phases,
+        ...(keep ? {} : { onFailure: [phase("Compensate", [step("postgresMigrationCompensate")])] }),
+    });
+    return { op };
+}

package/dist/postgres/migrate/receipts.js

@@ -0,0 +1,117 @@
+/**
+ * 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, which the
+ * backfill reaches directly. A sql project's `effect()` receipts use the same
+ * store over `chant_receipts.receipts` (`../../receipts.ts`).
+ */
+import { OWNERSHIP_MANAGED_BY_VALUE } from "@intentius/chant/ownership";
+import { COMMENT_OWNERSHIP_KEYS, hasChantTrailerKey, RECEIPTS_TRAILER_KEY } from "../../core/ownership.js";
+import { receiptAddress } from "../../core/receipts.js";
+import { quoteIdent } from "../keywords.js";
+/** 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.js";
+/** A receipts table chant did not make: a user's table under the same name. */
+export class ReceiptsTableConflict extends Error {
+    constructor(schema, table = POSTGRES_RECEIPTS_TABLE) {
+        super(`${schema}.${table} exists and is not chant's receipts table (its comment carries no receipts marker). ` +
+            `chant keeps its receipts under that name, so it stops rather than write into it; rename the table.`);
+        this.name = "ReceiptsTableConflict";
+    }
+}
+/**
+ * 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. `table` names the table in `schema`,
+ * `__chant_receipts` by default (`../../receipts.ts` keeps `effect()`
+ * receipts in `chant_receipts.receipts`).
+ */
+export function postgresReceiptStore(client, schema, identity, opts = {}) {
+    const name = opts.table ?? POSTGRES_RECEIPTS_TABLE;
+    const table = `${quoteIdent(schema)}.${quoteIdent(name)}`;
+    let ensured = false;
+    const comment = async () => {
+        const [row] = await client.query("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 () => {
+        if (ensured)
+            return true;
+        const c = await comment();
+        if (c === undefined)
+            return false;
+        if (!hasChantTrailerKey(c ?? undefined, [RECEIPTS_TRAILER_KEY]))
+            throw new ReceiptsTableConflict(schema, name);
+        return true;
+    };
+    const address = (receipt) => 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(`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(`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(`DELETE FROM ${table} WHERE starts_with(address, $1) RETURNING address`, [prefix]);
+            const [left] = await client.query(`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/dist/postgres/migrate/replication.js

@@ -0,0 +1,106 @@
+/**
+ * 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.
+ */
+export const DEFAULT_REPLICATION_LAG = { maxLagMs: 10000, waitMs: 30 * 60000 };
+/** A replica that stayed behind past the wait, or whose lag this role cannot read. */
+export class ReplicationLagError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = "ReplicationLagError";
+    }
+}
+/** The WAL senders on this server and how far behind each replica's replay is. */
+export async function replicaLags(client) {
+    const rows = await client.query(`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, bound, opts = {}) {
+    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(1000, bound.waitMs - waited), opts.signal);
+    }
+}
+/**
+ * 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, schema, table, column, major) {
+    if (major >= 15) {
+        const rows = await client.query(`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("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, signal) {
+    return new Promise((resolve, reject) => {
+        const t = setTimeout(resolve, ms);
+        signal?.addEventListener("abort", () => {
+            clearTimeout(t);
+            reject(signal.reason);
+        }, { once: true });
+    });
+}