@quereus/quereus 4.8.0 → 4.10.0

package/dist/src/schema/rename/table-rename.d.ts

@@ -0,0 +1,263 @@
+import type * as AST from '../../parser/ast.js';
+import { type ResolveObjectRef, type TableRenameTarget } from './shared.js';
+/**
+ * Scope-aware, in-place table-reference walker: propagates
+ * `ALTER TABLE … RENAME` into dependent object ASTs (view bodies, CHECK
+ * expressions, assertion bodies, partial-index predicates, column DEFAULT /
+ * generated expressions) and answers the read-only "does this AST reference
+ * table X?" probe the DROP guards use.
+ *
+ * All three verbs are expressed over ONE traversal ({@link visitTableRefs}),
+ * which reports every REAL table reference — one not shadowed by a CTE, a FROM
+ * alias, or the `new.`/`old.` row image — to a sink. The rewrite sink renames
+ * matching references in place; the probe sink records a match and stops the
+ * walk; the collect sink ({@link collectTableRefsInAst}) keys every reference
+ * for the reachability closure the DROP guards follow through view chains. One
+ * traversal is the invariant, not an implementation detail: the DROP guards
+ * must refuse exactly the references a rename would rewrite.
+ *
+ * All name comparisons are case-insensitive to match the Quereus catalog
+ * rules. Walkers mutate the input AST and return whether anything changed, so
+ * callers can skip cloning when nothing matched.
+ */
+/** Options for the table-reference walk, threaded from the entry points. */
+export interface TableRenameOpts {
+    /**
+     * The walked expression is evaluated against a WRITTEN ROW — a CHECK
+     * constraint or a column DEFAULT / generated body — so a bare `new.` /
+     * `old.` column qualifier names the row image, never a table called `new`
+     * or `old`. Suppression is scope-aware: it applies only while no FROM/WITH
+     * frame rebinds the qualifier (a subquery selecting from a real table
+     * named `new` still counts as a table reference), and never to a
+     * schema-qualified `main.new.a`, which is a real three-part reference.
+     *
+     * Deliberately NOT set for partial-index predicates: a predicate describes
+     * rows already stored and has no written-row context, so `new.x` there IS
+     * a table reference. (The column walker records the same asymmetry by
+     * passing row-image mode `'none'` for predicates.)
+     *
+     * A boolean where the column walker's
+     * {@link import('./shared.js').RowImageContext} is three-valued, and
+     * COMPLETE at two: this walker never *matches* a row image, only
+     * suppresses one, so the column walker's `'own'`/`'foreign'` split
+     * collapses — `false` maps to `'none'`, `true` to `'foreign'`. Like the
+     * column walker, the flag is overridden (to `true`) over `with inverse` /
+     * `with defaults` subtrees regardless of the entry-point value, because
+     * written-row context there is a property of the position, not the walk.
+     */
+    rowImageContext?: boolean;
+    /**
+     * The walked expression is SCHEMA-AUTHORED — a CHECK constraint, a column
+     * DEFAULT / generated body, or a partial-index predicate — so it plans under
+     * `schemaAuthoredContext` (`planner/building/schema-authored-context.ts`):
+     * its owning schema and NOTHING else, never the session schema path. Set by
+     * the three collection helpers below; absent for the stored bodies that DO
+     * plan under the home schema path (view bodies, materialized-view bodies,
+     * assertion checks).
+     *
+     * Suppresses the untouched-reference arm of {@link renameTableInAst}, for
+     * two reasons that agree:
+     *
+     * - Nothing is lost. That arm fires only when an unqualified name resolves
+     *   through to ANOTHER schema, which is precisely what this planning context
+     *   rejects — so it could only ever fire on a body the planner already
+     *   refuses to evaluate.
+     * - It keeps the walk IDEMPOTENT where idempotence is load-bearing. The
+     *   renamed table's own CHECK / predicate / column expressions are walked
+     *   more than once on purpose: `runRenameTable` rewrites them before the
+     *   catalog swap, `propagateTableRename` walks every table again afterwards,
+     *   and a persisting module rewrites the same shared ASTs inside its own
+     *   `renameTable` hook. The rewrite arm is idempotent by construction (after
+     *   it runs, nothing names `oldName`); the untouched arm is NOT, because a
+     *   reference the rewrite already turned into `newName` is indistinguishable
+     *   — to the resolvers — from one the new name captured. Confining that arm
+     *   to the once-walked home-path bodies is what keeps the two facts from
+     *   colliding.
+     */
+    schemaAuthoredBody?: boolean;
+}
+/**
+ * `target.resolve` and the derived `targetKey` (`objectRefKey(target.schemaName,
+ * target.oldName)`) decide matching for the rewrite and the probe below alike: a
+ * reference matches when `resolve(ref.schema, ref.name)` — the reference's
+ * planner-parity resolution under the WALKED BODY's home schema path — equals
+ * `targetKey`. The bare-name equality check in front is a pure short-circuit:
+ * the resolver echoes the name it is given into the key, so a reference spelled
+ * differently can never resolve to the target.
+ *
+ * The rewrite additionally enforces a POST-CONDITION the probe does not need,
+ * and it covers EVERY reference the walk reports — not only the ones it
+ * rewrites:
+ *
+ * > Walking a body for a rename, every reference must mean after the statement
+ * > exactly what it meant before.
+ *
+ * Both arms decide that the same way: re-resolve the reference under the same
+ * home schema path against the catalog AS IT WILL BE AFTER THE RENAME
+ * (`target.resolveAfter`) and compare with what it meant before.
+ *
+ * - A REWRITTEN reference must still yield the renamed object's key. When it
+ *   would not — the bare new name is captured by an earlier schema on the
+ *   body's home path — it is schema-qualified to the renamed schema via
+ *   {@link TableRef.qualify}.
+ * - An UNTOUCHED reference must still yield its own before-answer. A rename
+ *   also CREATES a name, and that new name can capture a reference the walk
+ *   never matched: a `temp`-owned body reading bare `k` (falling through to
+ *   `main.k`, because `temp` holds no `k`) silently re-binds to `temp.k` the
+ *   moment `alter table temp.other rename to k` lands, without its text ever
+ *   mentioning the renamed table. When the answer would change, the reference
+ *   is qualified to the schema its BEFORE-answer named — recovered from that
+ *   key by {@link import('./shared.js').objectRefKeySchema}. This arm applies
+ *   to the stored bodies that plan under the home schema path and is walked
+ *   ONCE per body; {@link TableRenameOpts.schemaAuthoredBody} turns it off for
+ *   the schema-authored expressions, which need it neither for correctness nor
+ *   for the re-walks they are deliberately subjected to — see that flag.
+ *
+ * The post-condition also covers the FROM-frame namespace, not just the
+ * catalog's: inside one body, the bare qualifier an unaliased FROM source
+ * exposes must keep binding that source. When the rename would give a source a
+ * name already visible as a qualifier where it sits ({@link
+ * TableRef.qualifierCollides}), the source pins its pre-rename spelling as an
+ * explicit alias ({@link TableRef.aliasAs}) and every column qualifier bound
+ * through it keeps the old spelling — `from t join u as t2` becomes
+ * `from t2 as t join u as t2` under `t → t2`, with `t.x` untouched. And when
+ * the new name is shadowed by a CTE in scope at the source ({@link
+ * TableRef.cteShadows}) — invisible to the catalog resolvers — the reference
+ * is schema-qualified so it cannot re-bind to the CTE.
+ *
+ * Qualification is conditional in both arms, never eager, so the common
+ * no-collision rename leaves body text (and a materialized view's `bodyHash`)
+ * exactly as before. A qualified reference resolves by passthrough, so its
+ * before- and after-answers are always equal and neither arm can fire on one;
+ * only unqualified references ever gain a qualifier. And only the NEW name can
+ * change meaning without being rewritten: removing the old name can only push a
+ * resolution later, and the references that resolved to the removed entry are
+ * exactly the ones the rewrite already matches — so there is no freed-name
+ * direction to handle.
+ *
+ * ALREADY-BROKEN BODIES: the resolver answers a total function — a name held by
+ * no schema on the path still gets a stable key, the home schema's — so a body
+ * naming an object that exists nowhere reads `before = <home>.<name>`, and a
+ * rename introducing that name in an earlier schema flips `after`. The
+ * untouched arm then qualifies the reference to the home schema, PINNING the
+ * pre-existing "no such table" failure rather than letting the body silently
+ * start reading the new arrival. That is the invariant-faithful answer, so no
+ * existence probe is added to dodge it (same reasoning as the seedless-qualifier
+ * emit site below: it only ever fires on an already-unevaluable body).
+ */
+export declare function renameTableInAst(node: AST.AstNode | undefined, target: TableRenameTarget, opts?: TableRenameOpts): boolean;
+/**
+ * Whether `node` refers to the table/view identified by `targetKey` (spelled
+ * `name`) — read-only, nothing is mutated.
+ *
+ * Deliberately the SAME traversal {@link renameTableInAst} uses — both are
+ * sinks over {@link visitTableRefs} — so "refers to" can never drift from
+ * "would have been rewritten by a rename". That equivalence is the whole
+ * point: the DROP guard refuses exactly the cases `ALTER TABLE … RENAME`
+ * would have followed. In particular, a body whose `with <name> as (…)`
+ * merely SHADOWS the probed name is not a reference — the walk skips it for
+ * both verbs. The probe's sink stops the walk at the first match.
+ *
+ * The column-level probes ({@link import('./column-rename.js').columnReferencedInAst},
+ * {@link import('./column-rename.js').columnReferencedInCheckExpression}) reach
+ * the same equivalence a different way — a real rename, to a sentinel name,
+ * over a throwaway clone — because the column walker has ~8 mutation points
+ * and a CTE-re-exposure branch that reads the new name; see their comments.
+ */
+export declare function tableReferencedInAst(node: AST.AstNode | undefined, name: string, resolve: ResolveObjectRef, targetKey: string, opts?: TableRenameOpts): boolean;
+/**
+ * Every real (non-shadowed) table / view reference in `node`, keyed the way
+ * {@link renameTableInAst} and {@link tableReferencedInAst} key their target:
+ * `resolve(ref.schema, ref.name)`, the reference's planner-parity resolution
+ * under the WALKED BODY's home schema path.
+ *
+ * The collect-all THIRD sink over the same {@link walkTableRefs} traversal, so
+ * it inherits the scope-awareness of the other two for free: a body whose
+ * `with t as (…)` merely SHADOWS the name contributes no `<schema>.t` key, a FROM
+ * alias contributes nothing, and a `new.` / `old.` row-image qualifier under
+ * {@link TableRenameOpts.rowImageContext} contributes nothing. That matters
+ * more here than anywhere else — a collect-everything walk is exactly where
+ * that property gets quietly lost, and the reachability closure built on this
+ * ({@link import('../object-dependency-closure.js').reachableObjects}) turns
+ * every key it yields into a refused DROP.
+ *
+ * The value is the object NAME the key was built from, lowercased. The
+ * resolver echoes the name it is given into the key, so this is always
+ * `ref.name.toLowerCase()`; it is returned rather than re-derived because a
+ * schema name may itself contain a dot, which makes splitting a key by
+ * separator scan wrong — see {@link import('./shared.js').objectRefKeySchema},
+ * whose whole job is that split and which needs exactly this.
+ */
+export declare function collectTableRefsInAst(node: AST.AstNode | undefined, resolve: ResolveObjectRef, opts?: TableRenameOpts): Map<string, string>;
+/**
+ * Rewrite the renamed table inside every partial-index predicate of `indexes`,
+ * in place. A predicate may carry a table-qualified self-reference
+ * (`create index ix on t (b) where t.b > 0`), which a table rename must follow.
+ *
+ * No {@link TableRenameOpts.rowImageContext}: a predicate describes rows
+ * already stored, so `new.x` there is a real table reference — see the flag's
+ * doc comment. {@link TableRenameOpts.schemaAuthoredBody} IS set: a predicate
+ * plans under its owning schema alone, and this AST is one of the several the
+ * rename walks more than once.
+ *
+ * Sharing and idempotence work exactly as in
+ * {@link import('./column-rename.js').renameColumnInIndexPredicates}: the
+ * predicate `Expression` is shared by reference with the catalog's
+ * `TableSchema` and with a unique partial index's `derivedFromIndex` UNIQUE
+ * constraint, so one in-place rewrite covers all of them, and a second call
+ * with the same pair finds nothing naming `oldName` and returns false.
+ */
+export declare function renameTableInIndexPredicates(indexes: ReadonlyArray<{
+    readonly predicate?: AST.Expression;
+}> | undefined, target: TableRenameTarget): boolean;
+/**
+ * Rewrite the renamed table inside every CHECK constraint expression of `checks`,
+ * in place. A CHECK may carry a table-qualified self-reference (`check (t.b > 0)`)
+ * exactly as a partial-index predicate may, and a table rename must follow it.
+ *
+ * A CHECK is evaluated against a written row, so the walk runs with
+ * {@link TableRenameOpts.rowImageContext}: a bare `new.a` / `old.a` names the
+ * row image and survives even a rename of a table literally called `new`. It
+ * also runs with {@link TableRenameOpts.schemaAuthoredBody}, for the same
+ * reasons the predicate arm above does.
+ *
+ * Same sharing and idempotence story as {@link renameTableInIndexPredicates}: the
+ * `expr` is the very AST the catalog's `TableSchema` holds, so one rewrite covers
+ * every holder and a second call with the same pair is a no-op.
+ */
+export declare function renameTableInCheckConstraints(checks: ReadonlyArray<{
+    readonly expr: AST.Expression;
+}> | undefined, target: TableRenameTarget): boolean;
+/**
+ * Rewrite the renamed table inside the two expressions a `ColumnSchema` can carry —
+ * a column DEFAULT (`w integer default ((select min(v) from u))`, however authored:
+ * inline, or via `ALTER TABLE … ALTER COLUMN … SET DEFAULT`, which writes the same
+ * field) and a generated column's body (`g integer generated always as ((select
+ * min(u.v) from u) + id)`) — in place.
+ *
+ * Both expressions evaluate against the row being written, so the walk runs
+ * with {@link TableRenameOpts.rowImageContext}: a default's `new.a` names the
+ * row image, not a table called `new`. It also runs with
+ * {@link TableRenameOpts.schemaAuthoredBody}, for the same reasons the two arms
+ * above do.
+ *
+ * Unlike the column-rename counterpart
+ * ({@link import('./column-rename.js').renameColumnInColumnExpressions}) there
+ * is no seeded/unseeded split: {@link renameTableInAst} resolves nothing against an
+ * implicit owning table, so the SAME entry point is correct for the renamed table's own
+ * columns (a self-referencing default, `default ((select count(*) from t))`) and for
+ * every other table's.
+ *
+ * Same sharing and idempotence story as {@link renameTableInCheckConstraints}: the
+ * `Expression` is the very AST the catalog's `TableSchema` holds, so one in-place
+ * rewrite reaches every holder and a second call with the same pair finds nothing
+ * naming `oldName` and returns false.
+ *
+ * The parameter is structurally typed rather than `ColumnSchema[]` so this module stays
+ * free of catalog imports; `ColumnSchema` satisfies it.
+ */
+export declare function renameTableInColumnExpressions(columns: ReadonlyArray<{
+    readonly defaultValue?: AST.Expression | null;
+    readonly generatedExpr?: AST.Expression;
+}> | undefined, target: TableRenameTarget): boolean;
+//# sourceMappingURL=table-rename.d.ts.map

package/dist/src/schema/rename/table-rename.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"table-rename.d.ts","sourceRoot":"","sources":["../../../../src/schema/rename/table-rename.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,KAAK,GAAG,MAAM,qBAAqB,CAAC;AAChD,OAAO,EAAqD,KAAK,gBAAgB,EAAE,KAAK,iBAAiB,EAAE,MAAM,aAAa,CAAC;AAE/H;;;;;;;;;;;;;;;;;;;GAmBG;AAEH,4EAA4E;AAC5E,MAAM,WAAW,eAAe;IAC/B;;;;;;;;;;;;;;;;;;;;;;OAsBG;IACH,eAAe,CAAC,EAAE,OAAO,CAAC;IAC1B;;;;;;;;;;;;;;;;;;;;;;;;;;;OA2BG;IACH,kBAAkB,CAAC,EAAE,OAAO,CAAC;CAC7B;AA6GD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAoEG;AACH,wBAAgB,gBAAgB,CAC/B,IAAI,EAAE,GAAG,CAAC,OAAO,GAAG,SAAS,EAC7B,MAAM,EAAE,iBAAiB,EACzB,IAAI,CAAC,EAAE,eAAe,GACpB,OAAO,CAoET;AAED;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,oBAAoB,CACnC,IAAI,EAAE,GAAG,CAAC,OAAO,GAAG,SAAS,EAC7B,IAAI,EAAE,MAAM,EACZ,OAAO,EAAE,gBAAgB,EACzB,SAAS,EAAE,MAAM,EACjB,IAAI,CAAC,EAAE,eAAe,GACpB,OAAO,CAUT;AAED;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,wBAAgB,qBAAqB,CACpC,IAAI,EAAE,GAAG,CAAC,OAAO,GAAG,SAAS,EAC7B,OAAO,EAAE,gBAAgB,EACzB,IAAI,CAAC,EAAE,eAAe,GACpB,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,CAUrB;AAED;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,4BAA4B,CAC3C,OAAO,EAAE,aAAa,CAAC;IAAE,QAAQ,CAAC,SAAS,CAAC,EAAE,GAAG,CAAC,UAAU,CAAA;CAAE,CAAC,GAAG,SAAS,EAC3E,MAAM,EAAE,iBAAiB,GACvB,OAAO,CAGT;AAED;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,6BAA6B,CAC5C,MAAM,EAAE,aAAa,CAAC;IAAE,QAAQ,CAAC,IAAI,EAAE,GAAG,CAAC,UAAU,CAAA;CAAE,CAAC,GAAG,SAAS,EACpE,MAAM,EAAE,iBAAiB,GACvB,OAAO,CAGT;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AACH,wBAAgB,8BAA8B,CAC7C,OAAO,EAAE,aAAa,CAAC;IACtB,QAAQ,CAAC,YAAY,CAAC,EAAE,GAAG,CAAC,UAAU,GAAG,IAAI,CAAC;IAC9C,QAAQ,CAAC,aAAa,CAAC,EAAE,GAAG,CAAC,UAAU,CAAC;CACxC,CAAC,GAAG,SAAS,EACd,MAAM,EAAE,iBAAiB,GACvB,OAAO,CAOT"}