@intentius/chant-lexicon-sql 0.124.31 → 0.124.32

package/dist/postgres/migrate/batches.js

@@ -0,0 +1,122 @@
+/**
+ * How the backfill cuts a table into batches (#3281, #3322). A batch must be
+ * the same rows on every run, or a receipt written for it by one run would
+ * vouch for different rows in the next.
+ *
+ * - A primary key of one smallint, integer or bigint column: ranges of its
+ *   value, `[b * size, (b + 1) * size)`. Arithmetic, so nothing needs to be
+ *   remembered, and a batch is the same range however many rows were
+ *   written since.
+ * - Any other primary key (uuid, text, a timestamp, several columns):
+ *   ranges between recorded boundaries in the key's order. The first run
+ *   walks the key's index once, taking every `size`-th key as a boundary
+ *   (`WHERE key >= boundary ORDER BY key OFFSET size LIMIT 1`, so the walk
+ *   reads each key once and sorts nothing), and records the boundaries in
+ *   the receipt store, beside the batches' receipts, before any batch runs.
+ *   Every later run reads them back instead of walking again, so batch `i`
+ *   is `boundary[i] <= key < boundary[i + 1]` in every run. The first batch
+ *   has no lower bound and the last no upper one, so a row written since,
+ *   anywhere in the key's order, falls in exactly one batch (and the dual
+ *   write has already filled it). Each batch is a range scan of the primary
+ *   key's index, with a row comparison (`(a, b) >= ($1, $2)`) in the index's
+ *   own column order.
+ *
+ * Hash buckets (`hash(key) % n`) were the other option: they need nothing
+ * recorded but the bucket count, but no index can serve them, so every batch
+ * would read the whole table. Ranges recorded once read each row once.
+ *
+ * The record is bound to the table's oid and the new column's attribute
+ * number, like the batches' receipts: a migration started again after
+ * onFailure (which drops the new column and the receipts) walks the key
+ * again. A record left from another batch size is kept, since its batches'
+ * receipts are what the run resumes from.
+ */
+import { col } from "./names.js";
+export const INTEGER_KEY_TYPES = new Set(["smallint", "integer", "bigint"]);
+/** Whether the key is batched by arithmetic ranges of its one integer column. */
+export const isIntegerKey = (keys) => keys.length === 1 && INTEGER_KEY_TYPES.has(keys[0].type);
+/** `id`, or `(tenant_id, id)`. */
+export const keyText = (keys) => (keys.length === 1 ? keys[0].name : `(${keys.map((k) => k.name).join(", ")})`);
+const tuple = (keys) => (keys.length === 1 ? col(keys[0].name) : `(${keys.map((k) => col(k.name)).join(", ")})`);
+const placeholders = (keys, from) => {
+    const p = keys.map((k, i) => `$${from + i}::${k.type}`);
+    return keys.length === 1 ? p[0] : `(${p.join(", ")})`;
+};
+/** The batches of an integer key: one per range that holds rows. */
+export async function integerBatches(client, table, key, size) {
+    const k = col(key.name);
+    const rows = await client.query(`SELECT pg_catalog.floor(${k}::numeric / ${size})::bigint::text AS b FROM ${table} GROUP BY 1 ORDER BY 1`);
+    return rows.map(({ b }) => {
+        const lo = (BigInt(b) * BigInt(size)).toString();
+        const hi = ((BigInt(b) + 1n) * BigInt(size)).toString();
+        return { id: b, where: `${k} >= $1 AND ${k} < $2`, params: [lo, hi], inputs: { batch: b, size, key: key.name } };
+    });
+}
+/** The batches between recorded boundaries: `[undefined, b1)`, `[b1, b2)`, ..., `[bn, undefined)`, where `b0` is only where the walk started. */
+export function boundaryBatches(keys, bounds) {
+    const k = tuple(keys);
+    return bounds.map((lo, i) => {
+        const hi = bounds[i + 1];
+        const where = [];
+        const params = [];
+        if (i > 0) {
+            where.push(`${k} >= ${placeholders(keys, 1)}`);
+            params.push(...lo);
+        }
+        if (hi) {
+            where.push(`${k} < ${placeholders(keys, params.length + 1)}`);
+            params.push(...hi);
+        }
+        return {
+            id: `k${i}`,
+            where: where.join(" AND ") || "true",
+            params,
+            inputs: { batch: `k${i}`, key: keys.map((c) => c.name), lo: i > 0 ? lo : null, hi: hi ?? null },
+        };
+    });
+}
+/** Walk the key's order and take every `size`-th key: the boundaries the batches lie between. */
+export async function walkBoundaries(client, table, keys, size, signal) {
+    const select = keys.map((k, i) => `${col(k.name)}::text AS k${i}`).join(", ");
+    const order = keys.map((k) => col(k.name)).join(", ");
+    const values = (row) => (row ? keys.map((_, i) => String(row[`k${i}`])) : undefined);
+    const bounds = [];
+    let at = values((await client.query(`SELECT ${select} FROM ${table} ORDER BY ${order} LIMIT 1`))[0]);
+    while (at) {
+        signal?.throwIfAborted();
+        bounds.push(at);
+        at = values((await client.query(`SELECT ${select} FROM ${table} WHERE ${tuple(keys)} >= ${placeholders(keys, 1)} ORDER BY ${order} OFFSET ${size} LIMIT 1`, at))[0]);
+    }
+    return bounds;
+}
+/**
+ * The boundary batches of a key that is not one integer column: read from
+ * the record in the receipt store, or walked and recorded when there is
+ * none for this table and new column.
+ */
+export async function recordedBatches(client, input) {
+    const ref = { name: input.effect, effect: input.effect, flavor: "hash", inputs: {} };
+    const keys = input.keys.map((k) => k.name);
+    const raw = await input.receipts.read(ref);
+    let record;
+    try {
+        const parsed = raw === undefined ? undefined : JSON.parse(raw);
+        if (parsed?.v === 1 && parsed.table === input.oid && parsed.column === input.attnum && JSON.stringify(parsed.keys) === JSON.stringify(keys))
+            record = parsed;
+    }
+    catch {
+        record = undefined;
+    }
+    let walked = false;
+    if (!record) {
+        const bounds = await walkBoundaries(client, input.table, input.keys, input.size, input.signal);
+        record = { v: 1, table: input.oid, column: input.attnum, keys, size: input.size, bounds };
+        await input.receipts.write(ref, JSON.stringify(record));
+        walked = true;
+        input.log(`-- batches of ${keyText(input.keys)}: ${bounds.length} boundary(ies) every ${input.size} key(s), recorded`);
+    }
+    else if (record.size !== input.size) {
+        input.log(`-- batches of ${keyText(input.keys)}: kept as recorded every ${record.size} key(s); batchSize ${input.size} applies to a migration started again`);
+    }
+    return { batches: boundaryBatches(input.keys, record.bounds), record, walked };
+}

package/dist/postgres/migrate/carry.js

@@ -0,0 +1,518 @@
+/**
+ * What uses the migrated column, carried over to the new one (#3322).
+ *
+ * An index, a constraint or a view on the column binds the column by its
+ * attribute number, not its name, so a swap of names at the switch would
+ * leave it on the old column, and the contract could not drop that column
+ * while something uses it. Each is made again on the new column before the
+ * switch, under a working name, and the switch swaps the names:
+ *
+ * | On the old column | Before the switch | In the switch's transaction |
+ * |---|---|---|
+ * | an index | `CREATE INDEX CONCURRENTLY` on the new column | the old one dropped (a type change) or kept as `<name>__chant_old` (a rename), the new one renamed to the name |
+ * | a primary key or unique constraint | its unique index built `CONCURRENTLY` | the old constraint dropped (or a rename's unique one kept as `__chant_old`), `ADD CONSTRAINT ... USING INDEX` |
+ * | a check or foreign key, this table's or another's that references the column | added `NOT VALID`, then `VALIDATE` | the old one dropped, the new one renamed to the name |
+ * | a view (and the views that read it) | nothing | dropped, then created again from its declaration once the columns are swapped, with its grants and owner |
+ *
+ * `CREATE INDEX CONCURRENTLY` reads the table without blocking writes, and
+ * `VALIDATE CONSTRAINT` holds SHARE UPDATE EXCLUSIVE, so both run while the
+ * application keeps writing; the dual-write trigger keeps the new column
+ * equal to the old one, so the index and the constraints hold the same rows
+ * as the old ones. A foreign key from another table is added against the
+ * new column's working unique index, which the switch then attaches to the
+ * key constraint. Everything in the switch changes only the catalog.
+ *
+ * Working objects carry chant's trailer with `migration=<key>` and
+ * `role=carry`, so the catalog read leaves them out of plans until the
+ * switch, and onFailure drops them (`./steps.ts`). The switch gives each its
+ * old comment back.
+ *
+ * Names: a type change keeps every name. A rename keeps a name the
+ * declaration does not give otherwise, except one Postgres made from the
+ * old column (`users_email_key` becomes `users_login_key`); a key, foreign
+ * key or index the build declares on the new column takes the declared name.
+ *
+ * Refused, each named with what to do: exclusion constraints and constraint
+ * triggers (no `USING INDEX` form), materialized views (made again only by
+ * a full scan in the switch), rules, triggers, policies and statistics on the
+ * column, a generated column computed from it, an INVALID index on it, a view
+ * the build does not declare, a view something other than a view depends on.
+ */
+import { quoteIdent } from "../keywords.js";
+import { tokenizeText } from "../tokens.js";
+import { identValue } from "../parser.js";
+import { createSteps, pgString } from "../apply/statements.js";
+import { POSTGRES_ENTITY_TYPES } from "../entity-types.js";
+import { canonicalName } from "../plan/normalize.js";
+import { pgName } from "./names.js";
+/** The working name of a carried object, and the name a rename keeps the old one under. */
+export const carriedWorkingName = (name) => pgName(`${name}__chant_new`);
+export const carriedOldName = (name) => pgName(`${name}__chant_old`);
+/**
+ * `sql` with every reference to the column `from` replaced by `to`: an
+ * identifier token naming it, not a qualifier (`x.`), a qualified name's
+ * last part, a function's name, a cast's type or an access method. Within
+ * `[start, end)` token indexes when given.
+ */
+export function replaceColumn(sql, from, to, range) {
+    const tokens = tokenizeText(sql, 0);
+    const ranges = range ? range(tokens) : [[0, tokens.length]];
+    const significant = (i, step) => {
+        for (let j = i + step; j >= 0 && j < tokens.length; j += step)
+            if (tokens[j].kind !== "ws" && tokens[j].kind !== "comment")
+                return tokens[j];
+        return undefined;
+    };
+    const inRange = (i) => ranges.some(([a, b]) => i >= a && i < b);
+    return tokens
+        .map((t, i) => {
+        if ((t.kind !== "ident" && t.kind !== "qident") || !inRange(i) || identValue(t) !== from)
+            return t.text;
+        const prev = significant(i, -1);
+        const next = significant(i, 1);
+        if (prev?.text === "." || next?.text === "." || next?.text === "(")
+            return t.text;
+        if (prev?.kind === "op" && prev.text === "::")
+            return t.text;
+        if (prev?.kind === "ident" && /^using$/i.test(prev.text))
+            return t.text;
+        return quoteIdent(to);
+    })
+        .join("");
+}
+/**
+ * A foreign key's token ranges: the referencing side (before `REFERENCES`,
+ * and an `ON DELETE SET NULL (...)` list after it) and the referenced
+ * column list.
+ */
+function foreignKeyRanges(tokens) {
+    const at = tokens.findIndex((t) => t.kind === "ident" && /^references$/i.test(t.text));
+    if (at < 0)
+        return { local: [[0, tokens.length]], referenced: [] };
+    let open = at + 1;
+    while (open < tokens.length && !(tokens[open].kind === "punct" && tokens[open].text === "("))
+        open++;
+    let close = open;
+    for (let depth = 0; close < tokens.length; close++) {
+        if (tokens[close].text === "(")
+            depth++;
+        else if (tokens[close].text === ")" && --depth === 0)
+            break;
+    }
+    return { local: [[0, at], [close + 1, tokens.length]], referenced: open < tokens.length ? [[open, close + 1]] : [] };
+}
+/** A foreign key's body with the column replaced on the side(s) that are the migrated table. */
+export function replaceInForeignKey(def, from, to, sides) {
+    return replaceColumn(def, from, to, (tokens) => {
+        const r = foreignKeyRanges(tokens);
+        return [...(sides.local ? r.local : []), ...(sides.referenced ? r.referenced : [])];
+    });
+}
+/** A constraint's body without a trailing `NOT VALID`, which the carry adds itself. */
+const withoutNotValid = (def) => def.replace(/\s+NOT VALID\s*$/i, "");
+/**
+ * `CREATE [UNIQUE] INDEX <name> ON ...` as `pg_get_indexdef` prints it, as
+ * the `CONCURRENTLY` build of `working` on the new column.
+ */
+export function carriedIndexStatement(def, working, from, to) {
+    const m = /^CREATE (UNIQUE )?INDEX (?:"(?:[^"]|"")+"|\S+) ON (.*)$/s.exec(def);
+    if (!m)
+        throw new Error(`unexpected index definition: ${def}`);
+    return `CREATE ${m[1] ?? ""}INDEX CONCURRENTLY ${quoteIdent(working)} ON ${replaceColumn(m[2], from, to)}`;
+}
+/**
+ * The name Postgres gives an object it names after its columns
+ * (`users_email_key`, `orders_user_id_fkey`, `users_email_idx`), when `name`
+ * is that name for the old columns: the same name for the new ones. Only a
+ * name that fits untruncated; any other name is kept.
+ */
+export function renamedDefault(name, table, oldCols, newCols, suffix) {
+    const made = (cols) => `${table}_${cols.join("_")}_${suffix}`;
+    if (name !== made(oldCols))
+        return undefined;
+    const next = made(newCols);
+    return Buffer.byteLength(next, "utf8") <= 63 && next !== name ? next : undefined;
+}
+const sameColumns = (a, b) => a.length === b.length && a.every((c, i) => c === b[i]);
+/** What uses the column the values come from, sorted into what the Op carries over and what it refuses. */
+export async function discoverDependents(input) {
+    const { client, names: n, oid, attnum } = input;
+    const from = n.source;
+    const to = n.newColumn;
+    const deps = await client.query(`SELECT d.deptype::text AS deptype, CASE d.classid WHEN 'pg_catalog.pg_constraint'::pg_catalog.regclass THEN 'constraint' WHEN 'pg_catalog.pg_class'::pg_catalog.regclass THEN 'class'
+                           WHEN 'pg_catalog.pg_rewrite'::pg_catalog.regclass THEN 'rewrite' WHEN 'pg_catalog.pg_attrdef'::pg_catalog.regclass THEN 'attrdef' ELSE 'other' END AS kind,
+            d.objid::text AS objid, d.objsubid, pg_catalog.pg_describe_object(d.classid, d.objid, d.objsubid) AS what
+     FROM pg_catalog.pg_depend d
+     WHERE d.refclassid = 'pg_catalog.pg_class'::pg_catalog.regclass AND d.refobjid = $1::oid AND d.refobjsubid = $2 AND d.deptype IN ('n', 'a', 'i')
+     UNION
+     SELECT 'n', 'constraint', c.oid::text, 0, pg_catalog.pg_describe_object('pg_catalog.pg_constraint'::pg_catalog.regclass, c.oid, 0)
+     FROM pg_catalog.pg_constraint c WHERE c.confrelid = $1::oid AND $2 = ANY(c.confkey)`, [oid, attnum]);
+    const refused = [];
+    const carried = [];
+    let sequence;
+    const byKind = (k) => [...new Set(deps.filter((d) => d.kind === k).map((d) => d.objid))];
+    const table = n.table;
+    const rename = n.change === "rename";
+    const tprops = input.declared.props;
+    // ── constraints ─────────────────────────────────────────────────────
+    const constraintIds = byKind("constraint");
+    const keyIndexes = new Set();
+    if (constraintIds.length > 0) {
+        const rows = await client.query(`SELECT c.oid::text AS oid, c.conname AS name, c.contype::text AS type, c.conrelid::text AS rel, c.confrelid::text AS frel, c.conindid::text AS idx,
+              pg_catalog.pg_get_constraintdef(c.oid) AS def, c.convalidated AS validated, c.condeferrable AS deferrable, c.condeferred AS deferred,
+              pg_catalog.obj_description(c.oid, 'pg_constraint') AS comment, n.nspname AS schema, t.relname AS table_name,
+              CASE WHEN c.conindid <> 0 THEN pg_catalog.obj_description(c.conindid, 'pg_class') END AS index_comment,
+              CASE WHEN c.conindid <> 0 AND c.contype IN ('p', 'u') THEN pg_catalog.pg_get_indexdef(c.conindid) END AS indexdef,
+              COALESCE(i.indisreplident, false) AS replident, COALESCE(i.indisclustered, false) AS clustered,
+              (SELECT a.attname FROM pg_catalog.pg_attribute a WHERE a.attrelid = c.conrelid AND a.attnum = c.conkey[1]) AS first_col,
+              ARRAY(SELECT a.attname FROM pg_catalog.unnest(c.conkey) WITH ORDINALITY k(n, o) JOIN pg_catalog.pg_attribute a ON a.attrelid = c.conrelid AND a.attnum = k.n ORDER BY k.o)::text[] AS cols,
+              t.relkind = 'p' OR EXISTS (SELECT 1 FROM pg_catalog.pg_class f WHERE f.oid = c.confrelid AND f.relkind = 'p') AS frel_partitioned
+       FROM pg_catalog.pg_constraint c JOIN pg_catalog.pg_class t ON t.oid = c.conrelid JOIN pg_catalog.pg_namespace n ON n.oid = t.relnamespace
+       LEFT JOIN pg_catalog.pg_index i ON i.indexrelid = c.conindid
+       WHERE c.oid = ANY($1::oid[]) ORDER BY c.conname`, [constraintIds]);
+        for (const r of rows) {
+            const name = String(r.name);
+            const own = String(r.rel) === oid;
+            const where = `${String(r.schema)}.${String(r.table_name)}`;
+            const qtable = `${quoteIdent(String(r.schema))}.${quoteIdent(String(r.table_name))}`;
+            const type = String(r.type);
+            if (type === "n" && own)
+                continue; // the column's own NOT NULL (18)
+            const comment = r.comment === null ? undefined : String(r.comment);
+            const base = { name, table: qtable, tableName: where, tableOid: String(r.rel), schema: String(r.schema), working: carriedWorkingName(name), validated: r.validated === true, ...(comment !== undefined ? { comment } : {}) };
+            const cols = r.cols ?? [];
+            const newCols = cols.map((c) => (own && c === from ? n.column : c));
+            if (input.partitioned && (type === "p" || type === "u" || type === "f")) {
+                keyIndexes.add(String(r.idx));
+                refused.push(`${type === "f" ? "foreign key" : type === "p" ? "primary key" : "unique constraint"} ${name} on ${where}: on a partitioned table ${type === "f" ? "a foreign key cannot be added NOT VALID and validated while writes go on" : "a key cannot be attached from an index built CONCURRENTLY (ADD CONSTRAINT ... USING INDEX is not supported on partitioned tables)"}, so carrying it over would hold ACCESS EXCLUSIVE for a full build; drop it, migrate, then declare it again (chant #3333)`);
+                continue;
+            }
+            if (type === "f" && !own && r.frel_partitioned === true) {
+                refused.push(`foreign key ${name} on ${where} references a partitioned table, where it cannot be added NOT VALID and validated while writes go on; drop it, migrate, then declare it again`);
+                continue;
+            }
+            if (type === "p" || type === "u") {
+                keyIndexes.add(String(r.idx));
+                const declaredKey = type === "p" ? (tprops.primaryKey?.name ? tprops.primaryKey : undefined) : tprops.uniques?.find((u) => u.name && sameColumns(u.columns, newCols));
+                const target = !rename ? name : (declaredKey?.name ?? (type === "u" ? renamedDefault(name, table, cols, newCols, "key") : undefined) ?? name);
+                const deferral = r.deferrable === true ? ` DEFERRABLE${r.deferred === true ? " INITIALLY DEFERRED" : ""}` : "";
+                carried.push({
+                    ...base,
+                    kind: "key",
+                    target,
+                    primary: type === "p",
+                    ...(deferral ? { deferral } : {}),
+                    definition: carriedIndexStatement(String(r.indexdef), base.working, from, to),
+                    ...(r.index_comment !== null && r.index_comment !== undefined ? { indexComment: String(r.index_comment) } : {}),
+                    ...(r.replident === true ? { replicaIdentity: true } : {}),
+                    ...(r.clustered === true ? { clustered: true } : {}),
+                });
+            }
+            else if (type === "c") {
+                const first = String(r.first_col ?? "");
+                const target = !rename ? name : (renamedDefault(name, table, [first], [first === from ? n.column : first], "check") ?? name);
+                carried.push({ ...base, kind: "check", target, definition: replaceColumn(withoutNotValid(String(r.def)), from, to) });
+            }
+            else if (type === "f") {
+                const referenced = String(r.frel) === oid;
+                const def = replaceInForeignKey(withoutNotValid(String(r.def)), from, to, { local: own, referenced });
+                let target = name;
+                if (rename && own) {
+                    const declaredFk = tprops.foreignKeys?.find((f) => f.name && sameColumns(f.columns, newCols));
+                    target = declaredFk?.name ?? renamedDefault(name, table, cols, newCols, "fkey") ?? name;
+                }
+                carried.push({ ...base, kind: "foreign-key", target, definition: def });
+            }
+            else if (type === "x") {
+                refused.push(`exclusion constraint ${name} on ${where}: an exclusion constraint cannot be attached from an index built CONCURRENTLY, so adding it again would hold ACCESS EXCLUSIVE for a full build; drop it, migrate, then declare it again`);
+            }
+            else if (type === "t") {
+                refused.push(`constraint trigger ${name} on ${where}: its function reads the column by name, which the Op cannot rewrite; drop it, migrate, then create it again`);
+            }
+            else {
+                refused.push(`constraint ${name} on ${where} (type ${type})`);
+            }
+        }
+    }
+    // ── indexes, sequences, columns ─────────────────────────────────────
+    const classIds = byKind("class");
+    if (classIds.length > 0) {
+        const rows = await client.query(`SELECT c.oid::text AS oid, c.relname AS name, c.relkind::text AS kind, n.nspname AS schema, pg_catalog.obj_description(c.oid, 'pg_class') AS comment,
+              CASE WHEN c.relkind IN ('i', 'I') THEN pg_catalog.pg_get_indexdef(c.oid) END AS def,
+              i.indisvalid AS valid, i.indisunique AS is_unique, COALESCE(i.indisreplident, false) AS replident, COALESCE(i.indisclustered, false) AS clustered,
+              ARRAY(SELECT a.attname FROM pg_catalog.unnest(i.indkey::int2[]) WITH ORDINALITY k(n, o) JOIN pg_catalog.pg_attribute a ON a.attrelid = i.indrelid AND a.attnum = k.n ORDER BY k.o)::text[] AS cols,
+              i.indexprs IS NOT NULL OR i.indpred IS NOT NULL AS has_exprs
+       FROM pg_catalog.pg_class c JOIN pg_catalog.pg_namespace n ON n.oid = c.relnamespace LEFT JOIN pg_catalog.pg_index i ON i.indexrelid = c.oid
+       WHERE c.oid = ANY($1::oid[]) ORDER BY c.relname`, [classIds]);
+        const declaredIndexes = input.objects.filter((o) => o.type === POSTGRES_ENTITY_TYPES.index);
+        for (const r of rows) {
+            const name = String(r.name);
+            const kind = String(r.kind);
+            if (kind === "i" || kind === "I") {
+                if (keyIndexes.has(String(r.oid)))
+                    continue;
+                if (kind === "I") {
+                    refused.push(`index ${r.schema}.${name} is a partitioned index, which cannot be built CONCURRENTLY; drop it, migrate, then declare it again (chant #3333)`);
+                    continue;
+                }
+                if (r.valid !== true) {
+                    refused.push(`index ${r.schema}.${name} is INVALID (a failed CONCURRENTLY build); drop it, or REINDEX it, first`);
+                    continue;
+                }
+                const working = carriedWorkingName(name);
+                let target = name;
+                if (rename) {
+                    const oldCols = r.cols ?? [];
+                    const cols = oldCols.map((c) => (c === from ? n.column : c));
+                    const declaredIndex = r.has_exprs === true
+                        ? undefined
+                        : declaredIndexes.find((d) => {
+                            const p = d.props;
+                            const els = p.elements ?? [];
+                            return (canonicalName(String(p.tableName ?? ""), input.defaultSchema) === `${n.schema}.${n.table}` &&
+                                (p.unique === true) === (r.is_unique === true) &&
+                                !p.where &&
+                                els.every((e) => e.column !== undefined) &&
+                                sameColumns(els.map((e) => e.column), cols));
+                        });
+                    target = declaredIndex?.canonical.name ?? (r.has_exprs === true ? undefined : renamedDefault(name, table, oldCols, cols, "idx")) ?? name;
+                }
+                carried.push({
+                    kind: "index",
+                    name,
+                    table: n.qualifiedTable,
+                    tableName: `${n.schema}.${n.table}`,
+                    tableOid: oid,
+                    schema: String(r.schema),
+                    working,
+                    target,
+                    definition: carriedIndexStatement(String(r.def), working, from, to),
+                    validated: true,
+                    ...(r.comment !== null ? { comment: String(r.comment) } : {}),
+                    ...(r.replident === true ? { replicaIdentity: true } : {}),
+                    ...(r.clustered === true ? { clustered: true } : {}),
+                });
+            }
+            else if (kind === "S") {
+                const dep = deps.find((d) => d.kind === "class" && d.objid === String(r.oid));
+                const seq = { kind: dep?.deptype === "i" ? "identity" : "serial", schema: String(r.schema), name, ident: `${quoteIdent(String(r.schema))}.${quoteIdent(name)}` };
+                if (rename) {
+                    refused.push(`sequence ${r.schema}.${name} gives the column its values (${seq.kind === "identity" ? "an identity column" : "a serial column's default"}); during a rename a writer that names the new column would be given the old one's next value by the trigger, which it cannot tell from a value the writer chose; a rename that keeps its sequence needs versioned views (chant #3331)`);
+                }
+                else
+                    sequence = seq;
+            }
+            else {
+                const what = deps.find((d) => d.kind === "class" && d.objid === String(r.oid))?.what ?? `${r.schema}.${name}`;
+                refused.push(what);
+            }
+        }
+    }
+    // ── generated columns computed from it ──────────────────────────────
+    const attrdefIds = byKind("attrdef");
+    if (attrdefIds.length > 0) {
+        const rows = await client.query("SELECT a.attname AS name, d.adnum FROM pg_catalog.pg_attrdef d JOIN pg_catalog.pg_attribute a ON a.attrelid = d.adrelid AND a.attnum = d.adnum WHERE d.oid = ANY($1::oid[])", [attrdefIds]);
+        for (const r of rows) {
+            if (Number(r.adnum) === attnum)
+                continue; // its own default
+            refused.push(`generated column ${n.schema}.${n.table}.${r.name} is computed from it; computing it from the new column would rewrite the table, so drop the generated column, migrate, then declare it again`);
+        }
+    }
+    // ── views, rules ────────────────────────────────────────────────────
+    const views = [];
+    const rewriteIds = byKind("rewrite");
+    if (rewriteIds.length > 0) {
+        const rows = await client.query(`WITH RECURSIVE v(oid, depth) AS (
+         SELECT r.ev_class, 0 FROM pg_catalog.pg_rewrite r WHERE r.oid = ANY($1::oid[]) AND r.ev_class <> $2::oid
+         UNION
+         SELECT r.ev_class, v.depth + 1 FROM v
+         JOIN pg_catalog.pg_depend d ON d.refclassid = 'pg_catalog.pg_class'::pg_catalog.regclass AND d.refobjid = v.oid AND d.classid = 'pg_catalog.pg_rewrite'::pg_catalog.regclass
+         JOIN pg_catalog.pg_rewrite r ON r.oid = d.objid AND r.ev_class <> v.oid
+       )
+       SELECT c.oid::text AS oid, n.nspname AS schema, c.relname AS name, c.relkind::text AS kind, max(v.depth) AS depth,
+              pg_catalog.pg_get_userbyid(c.relowner) AS owner,
+              ARRAY(SELECT CASE WHEN x.grantee = 0 THEN 'PUBLIC' ELSE pg_catalog.quote_ident(pg_catalog.pg_get_userbyid(x.grantee)) END || E'\\t' || x.privilege_type || E'\\t' || x.is_grantable::text
+                    FROM pg_catalog.aclexplode(c.relacl) x WHERE x.grantee <> c.relowner)::text[] AS grants,
+              ARRAY(SELECT pg_catalog.pg_describe_object(d.classid, d.objid, d.objsubid) FROM pg_catalog.pg_depend d
+                    WHERE d.refclassid = 'pg_catalog.pg_class'::pg_catalog.regclass AND d.refobjid = c.oid AND d.deptype = 'n'
+                      AND d.classid NOT IN ('pg_catalog.pg_rewrite'::pg_catalog.regclass, 'pg_catalog.pg_type'::pg_catalog.regclass))::text[] AS others
+       FROM v JOIN pg_catalog.pg_class c ON c.oid = v.oid JOIN pg_catalog.pg_namespace n ON n.oid = c.relnamespace
+       GROUP BY c.oid, n.nspname, c.relname, c.relkind, c.relowner, c.relacl ORDER BY 5, 2, 3`, [rewriteIds, oid]);
+        const ownRules = await client.query("SELECT r.rulename AS name FROM pg_catalog.pg_rewrite r WHERE r.oid = ANY($1::oid[]) AND r.ev_class = $2::oid", [rewriteIds, oid]);
+        for (const r of ownRules)
+            refused.push(`rule ${r.name} on ${n.schema}.${n.table} reads the column; drop it, migrate, then create it again`);
+        for (const r of rows) {
+            const name = `${String(r.schema)}.${String(r.name)}`;
+            if (r.kind === "m") {
+                refused.push(`materialized view ${name} reads the column; making it again would scan in the switch's transaction, so drop it, migrate, then declare it again`);
+                continue;
+            }
+            if (r.kind !== "v") {
+                refused.push(`${name} (relkind ${String(r.kind)}) reads the column`);
+                continue;
+            }
+            const others = r.others ?? [];
+            if (others.length > 0)
+                refused.push(`view ${name} is used by ${others.join(", ")}, which dropping and creating the view again would break`);
+            const declared = input.objects.find((o) => (o.type === POSTGRES_ENTITY_TYPES.view || o.type === POSTGRES_ENTITY_TYPES.materializedView) && `${o.canonical.schema ?? input.defaultSchema}.${o.canonical.name}` === name);
+            if (!declared) {
+                refused.push(`view ${name} reads ${rename ? `${from}, which the rename takes away` : "the column"}, and the build does not declare it; the switch makes each such view again from its declaration, so declare it (reading ${n.column}) in the build`);
+                continue;
+            }
+            if (declared.type !== POSTGRES_ENTITY_TYPES.view) {
+                refused.push(`view ${name} is declared as a ${declared.type}`);
+                continue;
+            }
+            views.push({
+                name,
+                ident: `${quoteIdent(String(r.schema))}.${quoteIdent(String(r.name))}`,
+                materialized: false,
+                depth: Number(r.depth),
+                declared,
+                owner: String(r.owner),
+                grants: (r.grants ?? []).map((g) => {
+                    const [grantee, privilege, grantable] = g.split("\t");
+                    return { grantee, privilege, grantable: grantable === "true" };
+                }),
+            });
+        }
+    }
+    for (const d of deps.filter((x) => x.kind === "other"))
+        refused.push(`${d.what} uses the column; drop it, migrate, then create it again`);
+    // A new name already taken by something else stops the switch; say so now.
+    const renamed = carried.filter((c) => c.target !== c.name);
+    if (renamed.length > 0) {
+        const taken = await client.query(`SELECT x.name FROM ROWS FROM (pg_catalog.unnest($1::text[]), pg_catalog.unnest($2::text[]), pg_catalog.unnest($3::oid[])) AS x(name, schema, rel)
+       WHERE EXISTS (SELECT 1 FROM pg_catalog.pg_class c JOIN pg_catalog.pg_namespace s ON s.oid = c.relnamespace WHERE s.nspname = x.schema AND c.relname = x.name)
+          OR EXISTS (SELECT 1 FROM pg_catalog.pg_constraint k WHERE k.conrelid = x.rel AND k.conname = x.name)`, [renamed.map((c) => c.target), renamed.map((c) => c.schema), renamed.map((c) => c.tableOid)]);
+        for (const t of taken)
+            refused.push(`${t.name}, the name ${renamed.find((c) => c.target === t.name).name} takes after the rename, is already used; rename that object first`);
+    }
+    return { carried, views, refused, ...(sequence ? { sequence } : {}) };
+}
+// ── statements ──────────────────────────────────────────────────────
+/** `ALTER TABLE ... ADD CONSTRAINT <working> <body> NOT VALID`: a check or foreign key on the new column. */
+export const addCarriedConstraint = (c) => `ALTER TABLE ${c.table} ADD CONSTRAINT ${quoteIdent(c.working)} ${c.definition} NOT VALID`;
+const commentOn = (what, text) => `COMMENT ON ${what} IS ${text === undefined ? "NULL" : pgString(text)}`;
+const indexIdent = (c, name) => `${quoteIdent(c.schema)}.${quoteIdent(name)}`;
+/**
+ * The switch's statements for the carried objects, around the swap of the
+ * columns: `before` drops the views and swaps every index and constraint;
+ * `after` creates the views again from their declarations once the column
+ * they read has its name.
+ *
+ * Foreign keys that reference the column go first: the old key constraint
+ * cannot be dropped while one depends on its index.
+ */
+export function carriedSwitchStatements(carried, views, change, oldComment, marker) {
+    const before = [];
+    const after = [];
+    for (const v of [...views].sort((a, b) => b.depth - a.depth))
+        before.push(`DROP VIEW ${v.ident}`);
+    const order = ["foreign-key", "check", "key", "index"];
+    const sorted = [...carried].sort((a, b) => order.indexOf(a.kind) - order.indexOf(b.kind));
+    for (const c of sorted) {
+        const keepOld = change === "rename" && (c.kind === "index" || (c.kind === "key" && !c.primary));
+        if (c.kind === "check" || c.kind === "foreign-key") {
+            before.push(`ALTER TABLE ${c.table} DROP CONSTRAINT ${quoteIdent(c.name)}`);
+            before.push(`ALTER TABLE ${c.table} RENAME CONSTRAINT ${quoteIdent(c.working)} TO ${quoteIdent(c.target)}`);
+            before.push(commentOn(`CONSTRAINT ${quoteIdent(c.target)} ON ${c.table}`, c.comment));
+        }
+        else if (c.kind === "key") {
+            if (keepOld) {
+                before.push(`ALTER TABLE ${c.table} RENAME CONSTRAINT ${quoteIdent(c.name)} TO ${quoteIdent(carriedOldName(c.name))}`);
+                before.push(commentOn(`CONSTRAINT ${quoteIdent(carriedOldName(c.name))} ON ${c.table}`, oldComment(c)));
+            }
+            else {
+                before.push(`ALTER TABLE ${c.table} DROP CONSTRAINT ${quoteIdent(c.name)}`);
+            }
+            before.push(`ALTER TABLE ${c.table} ADD CONSTRAINT ${quoteIdent(c.target)} ${c.primary ? "PRIMARY KEY" : "UNIQUE"} USING INDEX ${quoteIdent(c.working)}${c.deferral ?? ""}`);
+            before.push(commentOn(`CONSTRAINT ${quoteIdent(c.target)} ON ${c.table}`, c.comment));
+            before.push(commentOn(`INDEX ${indexIdent(c, c.target)}`, c.indexComment));
+        }
+        else {
+            if (keepOld) {
+                before.push(`ALTER INDEX ${indexIdent(c, c.name)} RENAME TO ${quoteIdent(carriedOldName(c.name))}`);
+                before.push(commentOn(`INDEX ${indexIdent(c, carriedOldName(c.name))}`, oldComment(c)));
+            }
+            else {
+                before.push(`DROP INDEX ${indexIdent(c, c.name)}`);
+            }
+            before.push(`ALTER INDEX ${indexIdent(c, c.working)} RENAME TO ${quoteIdent(c.target)}`);
+            before.push(commentOn(`INDEX ${indexIdent(c, c.target)}`, c.comment));
+        }
+        if (c.replicaIdentity)
+            before.push(`ALTER TABLE ${c.table} REPLICA IDENTITY USING INDEX ${quoteIdent(c.target)}`);
+        if (c.clustered)
+            before.push(`ALTER TABLE ${c.table} CLUSTER ON ${quoteIdent(c.target)}`);
+    }
+    for (const v of [...views].sort((a, b) => a.depth - b.depth)) {
+        for (const s of createSteps(v.declared, marker))
+            after.push(s.sql);
+        after.push(`ALTER VIEW ${v.ident} OWNER TO ${quoteIdent(v.owner)}`);
+        for (const g of v.grants)
+            after.push(`GRANT ${g.privilege} ON TABLE ${v.ident} TO ${g.grantee}${g.grantable ? " WITH GRANT OPTION" : ""}`);
+    }
+    return { before, after };
+}
+/** What the gate binds about the carried objects: each one's kind, names and definition, and each view. */
+export function carriedSubject(d) {
+    return {
+        ...(d.sequence ? { sequence: { kind: d.sequence.kind, name: `${d.sequence.schema}.${d.sequence.name}` } } : {}),
+        carried: d.carried.map((c) => ({ kind: c.kind, table: c.tableName, name: c.name, target: c.target, definition: c.definition, ...(c.primary !== undefined ? { primary: c.primary } : {}) })),
+        views: d.views.map((v) => ({ name: v.name, ddl: v.declared.ddl })),
+    };
+}
+/** Whether a declared column is NOT NULL once it is switched: declared so, an identity column, or part of a carried primary key. */
+export const requiresNotNull = (column, carried) => column.notNull === true || column.generated?.kind === "identity" || SERIAL_TYPES[column.type ?? ""] !== undefined || carried.some((c) => c.kind === "key" && c.primary === true);
+/** The integer type of each `serial` spelling: what the column holds, and the sequence's type. */
+export const SERIAL_TYPES = {
+    smallserial: "smallint",
+    serial2: "smallint",
+    serial: "integer",
+    serial4: "integer",
+    bigserial: "bigint",
+    serial8: "bigint",
+};
+/** A declared column's type as the server holds it: a `serial` spelling is its integer type. */
+export const storedType = (type) => (type === undefined ? undefined : (SERIAL_TYPES[type.replace(/^(public|pg_catalog)\./, "")] ?? type));
+/**
+ * The working copies of the carried objects on the server, by working name.
+ * One under a working name that is somebody else's is refused, as for the
+ * other working objects (`./observe.ts`).
+ */
+export async function carriedStates(client, carried, ours, refuse) {
+    const out = new Map();
+    const indexes = carried.filter((c) => c.kind === "index" || c.kind === "key");
+    const constraints = carried.filter((c) => c.kind === "check" || c.kind === "foreign-key");
+    if (indexes.length > 0) {
+        const rows = await client.query(`SELECT c.relname AS name, i.indisvalid AS valid, pg_catalog.obj_description(c.oid, 'pg_class') AS comment, pg_catalog.pg_get_indexdef(c.oid) AS def
+       FROM ROWS FROM (pg_catalog.unnest($1::text[]), pg_catalog.unnest($2::text[])) AS x(name, schema)
+       JOIN pg_catalog.pg_namespace s ON s.nspname = x.schema JOIN pg_catalog.pg_class c ON c.relnamespace = s.oid AND c.relname = x.name
+       LEFT JOIN pg_catalog.pg_index i ON i.indexrelid = c.oid`, [indexes.map((c) => c.working), indexes.map((c) => c.schema)]);
+        for (const r of rows) {
+            const c = indexes.find((x) => x.working === r.name);
+            const owner = ours(r.comment ?? undefined);
+            const expected = c.definition.replace(/ INDEX CONCURRENTLY /, " INDEX ");
+            if (owner === "theirs" || (owner === "none" && r.def !== expected))
+                refuse(`index ${c.schema}.${c.working}`);
+            out.set(c.working, { present: true, ready: r.valid === true, marked: owner === "ours" });
+        }
+    }
+    if (constraints.length > 0) {
+        const rows = await client.query(`SELECT k.conname AS name, k.conrelid::text AS rel, k.convalidated AS validated, pg_catalog.obj_description(k.oid, 'pg_constraint') AS comment
+       FROM ROWS FROM (pg_catalog.unnest($1::text[]), pg_catalog.unnest($2::oid[])) AS x(name, rel) JOIN pg_catalog.pg_constraint k ON k.conrelid = x.rel AND k.conname = x.name`, [constraints.map((c) => c.working), constraints.map((c) => c.tableOid)]);
+        for (const r of rows) {
+            const c = constraints.find((x) => x.working === r.name && x.tableOid === r.rel);
+            if (ours(r.comment ?? undefined) !== "ours")
+                refuse(`constraint ${c.working} on ${c.tableName}`);
+            out.set(c.working, { present: true, ready: r.validated === true || !c.validated, marked: true });
+        }
+    }
+    return out;
+}
+/** The carried objects whose working copy is not there, not marked, or not yet valid. */
+export const carriedNotReady = (carried, states) => carried.filter((c) => {
+    const s = states.get(c.working);
+    return !s || !s.ready || !s.marked;
+});