@pgsql/transform 18.5.0 → 18.7.0

package/esm/role-transform.js

@@ -0,0 +1,129 @@
+/**
+ * AST transform that applies a {@link RoleRouter}.
+ *
+ * Role identifiers surface in many statement forms. Most flow through a single
+ * `RoleSpec` node (grantees, ownership `... OWNER TO`, `CREATE POLICY ... TO`,
+ * `ALTER DEFAULT PRIVILEGES [FOR ROLE ...] ... TO`, `ALTER ROLE`, `DROP ROLE`,
+ * role-membership grantees, `GRANTED BY`, `REASSIGN OWNED BY`), which the
+ * traversal reaches automatically. Four positions carry a role name outside a
+ * `RoleSpec` and are handled explicitly:
+ *
+ * - `CREATE ROLE <name>` — a bare string on `CreateRoleStmt.role`.
+ * - `GRANT <role> TO ...` — the *granted* roles are `AccessPriv.priv_name`
+ *   strings on `GrantRoleStmt.granted_roles` (not `RoleSpec`s).
+ * - `SET ROLE` / `SET SESSION AUTHORIZATION` — the role is a string constant
+ *   in `VariableSetStmt.args`.
+ * - `ALTER ROLE <old> RENAME TO <new>` — `RenameStmt` with string
+ *   `subname`/`newname`.
+ *
+ * Reserved role specifications (`PUBLIC`, `CURRENT_USER`, `SESSION_USER`, ...)
+ * carry no `rolename` and a non-`CSTRING` `roletype`, so they are never
+ * rewritten.
+ */
+import { walk as walkSql } from '@pgsql/traverse';
+import { transformSync } from 'plpgsql-parser';
+import { RoleRouter } from './role-router';
+export function createRoleResult() {
+    return { rolesRenamed: new Map() };
+}
+const ROLE_SET_PARAMS = new Set(['role', 'session_authorization']);
+/**
+ * Create a SQL AST visitor that renames role identifiers against a router.
+ * Composable with the walkers used by the core transform.
+ */
+export function createRoleVisitor(router, result) {
+    const record = (name) => {
+        result.rolesRenamed.set(name, (result.rolesRenamed.get(name) ?? 0) + 1);
+    };
+    return {
+        RoleSpec: (path) => {
+            const node = path.node;
+            // Only named roles (ROLESPEC_CSTRING) carry a rolename; PUBLIC /
+            // CURRENT_USER / SESSION_USER are encoded by roletype and left alone.
+            if (node.roletype !== 'ROLESPEC_CSTRING')
+                return;
+            const target = router.resolve(node.rolename);
+            if (target === undefined)
+                return;
+            node.rolename = target;
+            record(node.rolename);
+        },
+        CreateRoleStmt: (path) => {
+            const node = path.node;
+            const target = router.resolve(node.role);
+            if (target === undefined)
+                return;
+            node.role = target;
+            record(target);
+        },
+        GrantRoleStmt: (path) => {
+            // granted_roles are role names carried as AccessPriv.priv_name (the
+            // grantee_roles RoleSpecs are handled by the RoleSpec visitor).
+            const granted = path.node.granted_roles;
+            if (!Array.isArray(granted))
+                return;
+            for (const g of granted) {
+                const priv = g?.AccessPriv;
+                if (!priv || typeof priv.priv_name !== 'string')
+                    continue;
+                const target = router.resolve(priv.priv_name);
+                if (target === undefined)
+                    continue;
+                priv.priv_name = target;
+                record(target);
+            }
+        },
+        VariableSetStmt: (path) => {
+            const node = path.node;
+            if (!ROLE_SET_PARAMS.has(node.name) || !Array.isArray(node.args))
+                return;
+            for (const arg of node.args) {
+                const sval = arg?.A_Const?.sval?.sval ?? arg?.String?.sval;
+                if (typeof sval !== 'string')
+                    continue;
+                const target = router.resolve(sval);
+                if (target === undefined)
+                    continue;
+                if (arg.A_Const?.sval)
+                    arg.A_Const.sval.sval = target;
+                else if (arg.String)
+                    arg.String.sval = target;
+                record(target);
+            }
+        },
+        RenameStmt: (path) => {
+            const node = path.node;
+            if (node.renameType !== 'OBJECT_ROLE')
+                return;
+            const subTarget = router.resolve(node.subname);
+            if (subTarget !== undefined) {
+                node.subname = subTarget;
+                record(subTarget);
+            }
+            const newTarget = router.resolve(node.newname);
+            if (newTarget !== undefined) {
+                node.newname = newTarget;
+                record(newTarget);
+            }
+        }
+    };
+}
+/**
+ * Apply role renaming to a SQL string: parse -> walk -> deparse. Role names in
+ * PL/pgSQL / `LANGUAGE sql` bodies are string literals (e.g. inside dynamic
+ * `EXECUTE`) and are intentionally not rewritten — see the module docs on why
+ * arbitrary string contents are out of scope.
+ */
+export function transformRoles(sql, router) {
+    const resolved = RoleRouter.from(router);
+    const result = createRoleResult();
+    const out = transformSync(sql, (ctx) => {
+        const stmts = ctx.sql?.stmts ?? [];
+        const visitor = createRoleVisitor(resolved, result);
+        for (const stmt of stmts) {
+            if (stmt?.stmt)
+                walkSql(stmt.stmt, visitor);
+        }
+    }, { hydrate: true, pretty: true });
+    return { sql: out, result };
+}

package/esm/router.js

@@ -20,6 +20,19 @@
  * `types` — matching `pg_class` / `pg_proc` / `pg_type`), mirroring the routing
  * model already used by {@link qualifyUnqualified}. Resolution is
  * object-route-first, then the schema-level default, then "leave unchanged".
+ *
+ * An object route may also *rebind* — change the object's **name**, not just
+ * the schema it lives in. Routing preserves identity (the same function, a new
+ * address); rebinding repoints a reference at a *different* object, which is
+ * what lets one implementation of a contract be substituted for another:
+ *
+ * ```ts
+ * { auth: { functions: { uid: { schema: null, name: 'current_user_id' } } } }
+ * // auth.uid()  ->  current_user_id()
+ * ```
+ *
+ * A `null` target schema de-qualifies the reference (relying on `search_path`),
+ * matching the convention used by the extension router.
  */
 const NS_BUCKET = {
     relation: 'relations',
@@ -71,6 +84,36 @@ export class SchemaRouter {
         }
         return false;
     }
+    /**
+     * True when any object route changes a name or de-qualifies (rather than
+     * only moving between schemas). Such rewrites cannot be expressed by the
+     * string-level passes at all, so callers use this to require the AST path.
+     */
+    hasNameRebinds() {
+        return this.nameRebinds().length > 0;
+    }
+    /**
+     * Every object route that rebinds a name or de-qualifies, keyed by source
+     * schema and namespace. Callers use this to report or verify substitutions.
+     */
+    nameRebinds() {
+        const out = [];
+        for (const [schema, route] of this.routes) {
+            for (const ns of ['relation', 'function', 'type']) {
+                const bucket = route[NS_BUCKET[ns]];
+                if (!bucket)
+                    continue;
+                for (const [from, target] of Object.entries(bucket)) {
+                    if (typeof target === 'string')
+                        continue;
+                    if (target.name === undefined && target.schema !== null)
+                        continue;
+                    out.push({ schema, ns, from, to: target });
+                }
+            }
+        }
+        return out;
+    }
     /** Every source schema this router may touch. */
     sourceSchemas() {
         return [...this.routes.keys()];
@@ -82,18 +125,39 @@ export class SchemaRouter {
      * to any object without a specific route.
      */
     resolve(sourceSchema, name, ns = 'unknown') {
+        // A `null` target de-qualifies the reference; the schema-only API cannot
+        // express that, so it reads as "unchanged" here.
+        return this.resolveObject(sourceSchema, name, ns)?.schema ?? undefined;
+    }
+    /**
+     * Resolve the full target for `(sourceSchema, name)` in namespace `ns` — both
+     * the schema the reference should live in and, when the route rebinds, the
+     * name it should be reached by. Returns `undefined` to leave it unchanged.
+     *
+     * In the result, `schema` is `null` when the reference should become
+     * unqualified and `undefined` when only the name changes; `name` is
+     * `undefined` when only the schema changes.
+     */
+    resolveObject(sourceSchema, name, ns = 'unknown') {
         if (!sourceSchema)
             return undefined;
         const route = this.routes.get(sourceSchema);
         if (!route)
             return undefined;
         if (name && (ns === 'relation' || ns === 'function' || ns === 'type')) {
-            const bucket = route[NS_BUCKET[ns]];
-            const mapped = bucket?.[name];
-            if (mapped !== undefined)
-                return mapped;
+            const target = route[NS_BUCKET[ns]]?.[name];
+            if (target !== undefined) {
+                if (typeof target === 'string')
+                    return { schema: target };
+                // An object route naming no schema inherits the schema-level default,
+                // so a pure rebind leaves placement alone.
+                return {
+                    schema: target.schema !== undefined ? target.schema : route.schema,
+                    name: target.name
+                };
+            }
         }
-        return route.schema;
+        return route.schema !== undefined ? { schema: route.schema } : undefined;
     }
     /**
      * Source schemas whose *every* object is guaranteed to move — i.e. those

package/esm/transform.js

@@ -80,12 +80,24 @@ export function transformNameList(names, schemaMapping, result, ns = 'unknown')
     const first = names[0];
     if (first?.String?.sval) {
         const schemaName = first.String.sval;
-        const objName = names[names.length - 1]?.String?.sval;
-        const newName = router.resolve(schemaName, objName, ns);
-        if (newName && newName !== schemaName) {
+        const last = names[names.length - 1];
+        const objName = last?.String?.sval;
+        const target = router.resolveObject(schemaName, objName, ns);
+        if (!target)
+            return;
+        if (target.name !== undefined && last?.String?.sval) {
             result.schemasFound.add(schemaName);
-            first.String.sval = newName;
-            result.schemasTransformed.set(schemaName, newName);
+            last.String.sval = target.name;
+        }
+        if (target.schema === null) {
+            // De-qualify: drop the schema element and rely on search_path.
+            result.schemasFound.add(schemaName);
+            names.splice(0, 1);
+        }
+        else if (target.schema && target.schema !== schemaName) {
+            result.schemasFound.add(schemaName);
+            first.String.sval = target.schema;
+            result.schemasTransformed.set(schemaName, target.schema);
         }
     }
 }
@@ -117,11 +129,22 @@ export function transformRelation(relation, schemaMapping, result) {
     const oldName = relation.schemaname;
     // A RangeVar names a relation (table/view/sequence/matview); route by the
     // relation name so object-level routes can send it to its own schema.
-    const newName = asRouter(schemaMapping).resolve(oldName, relation.relname, 'relation');
-    if (newName && newName !== oldName) {
+    const target = asRouter(schemaMapping).resolveObject(oldName, relation.relname, 'relation');
+    if (!target)
+        return;
+    if (target.name !== undefined && relation.relname) {
+        result.schemasFound.add(oldName);
+        relation.relname = target.name;
+    }
+    if (target.schema === null) {
+        // De-qualify: drop the schema qualifier and rely on search_path.
+        result.schemasFound.add(oldName);
+        delete relation.schemaname;
+    }
+    else if (target.schema && target.schema !== oldName) {
         result.schemasFound.add(oldName);
-        relation.schemaname = newName;
-        result.schemasTransformed.set(oldName, newName);
+        relation.schemaname = target.schema;
+        result.schemasTransformed.set(oldName, target.schema);
     }
 }
 /**

package/extension-router.d.ts

@@ -0,0 +1,161 @@
+/**
+ * Extension routing for the core transform.
+ *
+ * A PostgreSQL extension is installed into exactly one schema, and the objects
+ * it provides (functions, types, operators) live in that schema. Two databases
+ * can install the *same* extension into *different* schemas — one leaves it in
+ * `public`, another isolates it in a dedicated schema — so portable SQL must be
+ * able to move an extension's install site **and** rewrite every reference to
+ * the symbols it provides.
+ *
+ * This is a distinct problem from {@link SchemaRouter}, which routes objects the
+ * SQL itself creates. Here the objects are owned by an extension and are not
+ * declared in the script; the only way to know that a bare `crypt(...)` call
+ * belongs to `pgcrypto` (and must move when `pgcrypto` moves) is an
+ * **inventory** of which symbols each extension provides. That inventory is
+ * also **version-aware**: a symbol can graduate into the server core and cease
+ * to be extension-owned (the canonical case is `gen_random_uuid()`, provided by
+ * `pgcrypto` before PostgreSQL 13 and part of core `pg_catalog` from 13 on — it
+ * must never be routed on 13+).
+ *
+ * An {@link ExtensionRouter} answers two questions:
+ *
+ * - **install**: where should `CREATE EXTENSION <e>` (or `ALTER EXTENSION <e>
+ *   SET SCHEMA`) place the extension?
+ * - **reference**: given a reference to a symbol `(schema, name)` in namespace
+ *   `ns`, what schema should it live in now — including stripping the qualifier
+ *   entirely (relying on `search_path`) when the target is "unqualified".
+ *
+ * A schema of `null` denotes the **unqualified** site: a bare reference
+ * (`crypt(...)`) or installing an extension with no explicit `SCHEMA` clause.
+ * This makes the router fully bidirectional: `null -> 'extensions'` qualifies
+ * bare references, and `'extensions' -> null` strips them back to bare.
+ */
+/** PostgreSQL namespaces an extension symbol can occupy. */
+export type ExtensionSymbolNamespace = 'function' | 'type' | 'operator';
+/** A single symbol provided by an extension. */
+export interface ExtensionSymbol {
+    /** Bare symbol name (e.g. `crypt`, `citext`, `gen_random_uuid`). */
+    name: string;
+    /** Which namespace the symbol occupies. Defaults to `function`. */
+    namespace?: ExtensionSymbolNamespace;
+    /**
+     * Major PostgreSQL version at/after which this symbol is part of the server
+     * core (`pg_catalog`) rather than the extension. At or above this version
+     * the symbol is **never routed** — it resolves from `pg_catalog` regardless
+     * of where the extension lives. The classic case is `gen_random_uuid`
+     * (`coreSince: 13`).
+     */
+    coreSince?: number;
+}
+/** The set of symbols an extension provides. */
+export interface ExtensionDefinition {
+    /** Extension name as used in `CREATE EXTENSION <name>`. */
+    name: string;
+    /**
+     * Whether the extension is relocatable (`ALTER EXTENSION ... SET SCHEMA`
+     * succeeds). Informational for callers deciding *how* to move an existing
+     * install; the router never emits `SET SCHEMA` itself.
+     */
+    relocatable?: boolean;
+    /**
+     * A schema the extension is pinned to and cannot be moved out of (fixed by
+     * its control file, e.g. a geocoder that always creates its own schema).
+     * When set, the router refuses to route the extension's install or symbols.
+     */
+    fixedSchema?: string;
+    /** Symbols the extension provides. */
+    symbols: ExtensionSymbol[];
+}
+/**
+ * A routing rule for one extension. `to` is the destination install/reference
+ * schema (or `null` to strip qualification / install without a `SCHEMA`
+ * clause). `from` lists the schemas currently holding the extension that
+ * should be rewritten; a `null` entry additionally routes bare references.
+ * When `from` is omitted, references in **any** schema (and bare ones) are
+ * routed — useful when the source layout is unknown.
+ */
+export interface ExtensionRoute {
+    to: string | null;
+    from?: (string | null)[];
+}
+/** Routing specification keyed by extension name. */
+export type ExtensionRouteSpec = Record<string, ExtensionRoute>;
+/** A concrete rewrite instruction: from a schema (or bare) to a schema (or bare). */
+export interface SymbolRewrite {
+    /** Target schema, or `null` to make the reference unqualified. */
+    to: string | null;
+}
+export interface ExtensionRouterOptions {
+    /**
+     * The symbol inventory. Defaults to {@link COMMON_EXTENSIONS}. Callers can
+     * pass an augmented or replacement inventory (e.g. extended from live-catalog
+     * introspection).
+     */
+    inventory?: ExtensionDefinition[];
+    /**
+     * Target PostgreSQL major version, used to apply {@link ExtensionSymbol.coreSince}.
+     * Defaults to a high value so version-graduated symbols (e.g. `gen_random_uuid`)
+     * are treated as core and never routed unless a caller opts into an older
+     * version.
+     */
+    serverVersion?: number;
+}
+/**
+ * A curated, platform-agnostic inventory of common contrib/extension symbols.
+ * Intentionally minimal and conservative — only well-known, stable symbols are
+ * listed so routing never touches something it cannot prove belongs to the
+ * extension. Callers extend this via {@link ExtensionRouterOptions.inventory}.
+ */
+export declare const COMMON_EXTENSIONS: ExtensionDefinition[];
+/**
+ * Resolves install-schema and symbol-reference routing for extensions, backed
+ * by a version-aware symbol inventory.
+ */
+export declare class ExtensionRouter {
+    private readonly routes;
+    private readonly serverVersion;
+    private readonly definitions;
+    /** `${namespace}:${name}` -> providing extension (+ version predicate). */
+    private readonly symbolIndex;
+    constructor(routes?: ExtensionRouteSpec | Map<string, ExtensionRoute>, options?: ExtensionRouterOptions);
+    /**
+     * Build a router that moves the given extensions (default: every inventoried
+     * one) to a single `targetSchema`, rewriting their references from `public`
+     * and from bare (unqualified) sites. Passing `null` as `targetSchema` strips
+     * qualification instead (the "repollute public / rely on search_path"
+     * direction).
+     */
+    static toSchema(targetSchema: string | null, options?: ExtensionRouterOptions & {
+        extensions?: string[];
+        from?: (string | null)[];
+    }): ExtensionRouter;
+    /** Coerce a spec, map, or existing router into a router. */
+    static from(source: ExtensionRouter | ExtensionRouteSpec | Map<string, ExtensionRoute>, options?: ExtensionRouterOptions): ExtensionRouter;
+    /** True when no extension routes are configured. */
+    get size(): number;
+    /** Extension names this router may rewrite. */
+    routedExtensions(): string[];
+    /** True when any configured extension has inventoried symbols to rewrite. */
+    hasSymbolRoutes(): boolean;
+    /**
+     * Resolve the install schema for `CREATE EXTENSION <extname>` /
+     * `ALTER EXTENSION <extname> SET SCHEMA`. Returns:
+     * - a string to place/keep the extension in that schema,
+     * - `null` to install with no explicit `SCHEMA` clause (server default),
+     * - `undefined` to leave the statement unchanged (no route, or the extension
+     *   is pinned to a fixed schema).
+     */
+    resolveInstall(extname: string | undefined | null): string | null | undefined;
+    /**
+     * Resolve a rewrite for a reference to `(schema, name)` in namespace `ns`,
+     * where `schema` is `null` for a bare reference. Returns the target
+     * ({@link SymbolRewrite}) or `undefined` to leave the reference unchanged.
+     *
+     * A reference is rewritten only when the inventory proves the symbol belongs
+     * to a routed extension, the symbol has not graduated to core at the target
+     * server version, the current schema is one the route rewrites `from`, and
+     * the destination actually differs from where it already is.
+     */
+    resolveSymbol(schema: string | null | undefined, name: string | undefined, ns: ExtensionSymbolNamespace): SymbolRewrite | undefined;
+}