@pgsql/transform 18.5.0 → 18.6.0

package/esm/extension-router.js

@@ -0,0 +1,236 @@
+/**
+ * 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.
+ */
+const DEFAULT_SERVER_VERSION = 9999;
+/**
+ * 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 const COMMON_EXTENSIONS = [
+    {
+        name: 'pgcrypto',
+        relocatable: true,
+        symbols: [
+            { name: 'crypt' },
+            { name: 'gen_salt' },
+            { name: 'digest' },
+            { name: 'hmac' },
+            { name: 'encrypt' },
+            { name: 'decrypt' },
+            { name: 'encrypt_iv' },
+            { name: 'decrypt_iv' },
+            { name: 'gen_random_bytes' },
+            // Provided by pgcrypto before PG13; part of core pg_catalog from 13 on.
+            { name: 'gen_random_uuid', coreSince: 13 },
+            { name: 'pgp_sym_encrypt' },
+            { name: 'pgp_sym_decrypt' },
+            { name: 'pgp_pub_encrypt' },
+            { name: 'pgp_pub_decrypt' }
+        ]
+    },
+    {
+        name: 'uuid-ossp',
+        relocatable: true,
+        symbols: [
+            { name: 'uuid_generate_v1' },
+            { name: 'uuid_generate_v1mc' },
+            { name: 'uuid_generate_v3' },
+            { name: 'uuid_generate_v4' },
+            { name: 'uuid_generate_v5' },
+            { name: 'uuid_nil' }
+        ]
+    },
+    {
+        name: 'citext',
+        relocatable: true,
+        symbols: [
+            { name: 'citext', namespace: 'type' },
+            { name: 'citextin', namespace: 'function' },
+            { name: 'citext_hash', namespace: 'function' }
+        ]
+    },
+    {
+        name: 'pg_trgm',
+        relocatable: true,
+        symbols: [
+            { name: 'similarity' },
+            { name: 'show_trgm' },
+            { name: 'word_similarity' },
+            { name: 'strict_word_similarity' }
+        ]
+    },
+    {
+        name: 'ltree',
+        relocatable: true,
+        symbols: [
+            { name: 'ltree', namespace: 'type' },
+            { name: 'lquery', namespace: 'type' },
+            { name: 'ltxtquery', namespace: 'type' },
+            { name: 'subltree' },
+            { name: 'subpath' },
+            { name: 'nlevel' },
+            { name: 'lca' }
+        ]
+    },
+    {
+        name: 'hstore',
+        relocatable: true,
+        symbols: [{ name: 'hstore', namespace: 'type' }]
+    },
+    {
+        name: 'unaccent',
+        relocatable: true,
+        symbols: [{ name: 'unaccent' }]
+    }
+];
+/**
+ * Resolves install-schema and symbol-reference routing for extensions, backed
+ * by a version-aware symbol inventory.
+ */
+export class ExtensionRouter {
+    routes;
+    serverVersion;
+    definitions;
+    /** `${namespace}:${name}` -> providing extension (+ version predicate). */
+    symbolIndex;
+    constructor(routes = {}, options = {}) {
+        this.routes = routes instanceof Map ? new Map(routes) : new Map(Object.entries(routes));
+        this.serverVersion = options.serverVersion ?? DEFAULT_SERVER_VERSION;
+        const inventory = options.inventory ?? COMMON_EXTENSIONS;
+        this.definitions = new Map(inventory.map(def => [def.name, def]));
+        this.symbolIndex = new Map();
+        for (const def of inventory) {
+            for (const sym of def.symbols) {
+                const key = symbolKey(sym.namespace ?? 'function', sym.name);
+                // First definition wins; inventories should not double-claim a symbol.
+                if (!this.symbolIndex.has(key)) {
+                    this.symbolIndex.set(key, { extension: def.name, coreSince: sym.coreSince });
+                }
+            }
+        }
+    }
+    /**
+     * 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, options = {}) {
+        const inventory = options.inventory ?? COMMON_EXTENSIONS;
+        const names = options.extensions ?? inventory.map(d => d.name);
+        const from = options.from ?? ['public', null];
+        const spec = {};
+        for (const name of names)
+            spec[name] = { to: targetSchema, from };
+        return new ExtensionRouter(spec, options);
+    }
+    /** Coerce a spec, map, or existing router into a router. */
+    static from(source, options) {
+        if (source instanceof ExtensionRouter)
+            return source;
+        return new ExtensionRouter(source, options);
+    }
+    /** True when no extension routes are configured. */
+    get size() {
+        return this.routes.size;
+    }
+    /** Extension names this router may rewrite. */
+    routedExtensions() {
+        return [...this.routes.keys()];
+    }
+    /** True when any configured extension has inventoried symbols to rewrite. */
+    hasSymbolRoutes() {
+        for (const name of this.routes.keys()) {
+            const def = this.definitions.get(name);
+            if (def && !def.fixedSchema && def.symbols.length > 0)
+                return true;
+        }
+        return false;
+    }
+    /**
+     * 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) {
+        if (!extname)
+            return undefined;
+        const route = this.routes.get(extname);
+        if (!route)
+            return undefined;
+        if (this.definitions.get(extname)?.fixedSchema !== undefined)
+            return undefined;
+        return route.to;
+    }
+    /**
+     * 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, name, ns) {
+        if (!name)
+            return undefined;
+        const indexed = this.symbolIndex.get(symbolKey(ns, name));
+        if (!indexed)
+            return undefined;
+        // Graduated into core at/after the target server version — resolves from
+        // pg_catalog and must not be tied to the extension's schema.
+        if (indexed.coreSince !== undefined && this.serverVersion >= indexed.coreSince)
+            return undefined;
+        const route = this.routes.get(indexed.extension);
+        if (!route)
+            return undefined;
+        if (this.definitions.get(indexed.extension)?.fixedSchema !== undefined)
+            return undefined;
+        const current = schema ?? null;
+        if (route.from !== undefined && !route.from.includes(current))
+            return undefined;
+        if (current === route.to)
+            return undefined;
+        return { to: route.to };
+    }
+}
+function symbolKey(ns, name) {
+    return `${ns}:${name}`;
+}

package/esm/extension-transform.js

@@ -0,0 +1,202 @@
+/**
+ * AST transform that applies an {@link ExtensionRouter}.
+ *
+ * Unlike the schema transform — which only rewrites string *fields* already
+ * present on a node — moving an extension changes the **shape** of the AST:
+ *
+ * - `CREATE EXTENSION <e>` with no `SCHEMA` clause must gain one, which means
+ *   constructing a new `DefElem` node and attaching it to a (possibly absent)
+ *   `options` array; the reverse strips the `DefElem` (and empties `options`).
+ * - a bare `crypt(...)` reference gains a schema qualifier (a `String` node is
+ *   prepended to `funcname`), and the reverse removes it.
+ *
+ * All rewrites are AST-precise and driven by the router's version-aware symbol
+ * inventory, so built-ins that merely share a name with an extension symbol
+ * (and symbols that have graduated into core) are left untouched.
+ */
+import { walk as walkSql } from '@pgsql/traverse';
+import { Deparser, parseSql, transformSync, walk as walkPlpgsql } from 'plpgsql-parser';
+import { ExtensionRouter } from './extension-router';
+/** Create a fresh result tracker. */
+export function createExtensionResult() {
+    return { installsMoved: new Map(), symbolsRewritten: new Map() };
+}
+function schemaStringNode(schema) {
+    return { String: { sval: schema } };
+}
+/**
+ * Rewrite a (possibly schema-qualified) name list in place against the router.
+ * `names` is the node's own array (`funcname`, `TypeName.names`, ...); it is
+ * mutated in place so the enclosing node keeps referring to it.
+ */
+function rewriteNameList(names, router, ns, result) {
+    if (!Array.isArray(names) || names.length === 0)
+        return;
+    const parts = names.map((n) => n?.String?.sval);
+    if (parts.some(p => typeof p !== 'string'))
+        return; // non-identifier element (e.g. %type)
+    const name = parts[parts.length - 1];
+    const schema = parts.length >= 2 ? parts[parts.length - 2] : null;
+    const rewrite = router.resolveSymbol(schema, name, ns);
+    if (!rewrite)
+        return;
+    if (rewrite.to === null) {
+        // Strip qualification: keep only the bare name node.
+        names.splice(0, names.length - 1);
+    }
+    else if (schema === null) {
+        // Qualify a bare reference: prepend the target schema.
+        names.unshift(schemaStringNode(rewrite.to));
+    }
+    else {
+        // Requalify: rewrite the existing schema element.
+        names[names.length - 2].String.sval = rewrite.to;
+    }
+    result.symbolsRewritten.set(name, (result.symbolsRewritten.get(name) ?? 0) + 1);
+}
+/** Read/replace the `schema` DefElem inside a `CreateExtensionStmt.options`. */
+function setExtensionSchemaOption(node, target) {
+    const options = Array.isArray(node.options) ? node.options : [];
+    const idx = options.findIndex((opt) => opt?.DefElem?.defname === 'schema');
+    if (target === null) {
+        // Install with no explicit SCHEMA clause: remove any existing option.
+        if (idx === -1)
+            return false;
+        options.splice(idx, 1);
+        if (options.length === 0)
+            delete node.options;
+        else
+            node.options = options;
+        return true;
+    }
+    const defElem = {
+        DefElem: {
+            defname: 'schema',
+            arg: { String: { sval: target } },
+            defaction: 'DEFELEM_UNSPEC'
+        }
+    };
+    if (idx === -1) {
+        options.push(defElem);
+    }
+    else {
+        const existing = options[idx].DefElem;
+        if (existing.arg?.String?.sval === target)
+            return false;
+        existing.arg = { String: { sval: target } };
+    }
+    node.options = options;
+    return true;
+}
+/**
+ * Create a SQL AST visitor that applies extension routing. Composable with the
+ * walkers used by the core transform and by PL/pgSQL body traversal.
+ */
+export function createExtensionVisitor(router, result) {
+    const rewriteBody = router.hasSymbolRoutes();
+    return {
+        CreateExtensionStmt: (path) => {
+            const node = path.node;
+            const target = router.resolveInstall(node.extname);
+            if (target === undefined)
+                return;
+            if (setExtensionSchemaOption(node, target)) {
+                result.installsMoved.set(node.extname, target);
+            }
+        },
+        // ALTER EXTENSION <e> SET SCHEMA <newschema>. The walker does not recurse
+        // into AlterObjectSchemaStmt.object; a null target has no SET SCHEMA form
+        // (a schema must be named), so it is left unchanged.
+        AlterObjectSchemaStmt: (path) => {
+            const node = path.node;
+            if (node.objectType !== 'OBJECT_EXTENSION')
+                return;
+            const extname = node.object?.String?.sval;
+            const target = router.resolveInstall(extname);
+            if (typeof target !== 'string' || target === node.newschema)
+                return;
+            node.newschema = target;
+            result.installsMoved.set(extname, target);
+        },
+        FuncCall: (path) => {
+            rewriteNameList(path.node.funcname, router, 'function', result);
+        },
+        // The walker does not auto-recurse into CallStmt.funccall.
+        CallStmt: (path) => {
+            if (path.node.funccall) {
+                rewriteNameList(path.node.funccall.funcname, router, 'function', result);
+            }
+        },
+        TypeName: (path) => {
+            rewriteNameList(path.node.names, router, 'type', result);
+        },
+        CreateFunctionStmt: (path) => {
+            const node = path.node;
+            if (!rewriteBody)
+                return;
+            // LANGUAGE sql bodies are opaque strings to the walker; parse and rewrite
+            // them separately (PL/pgSQL bodies ride the hydrated walk in transformExtensions).
+            const isPlpgsql = (node.options ?? []).some((opt) => opt?.DefElem?.defname === 'language' &&
+                opt.DefElem.arg?.String?.sval === 'plpgsql');
+            if (isPlpgsql || !Array.isArray(node.options))
+                return;
+            for (const opt of node.options) {
+                if (opt?.DefElem?.defname === 'as' && opt.DefElem.arg?.List?.items) {
+                    for (const item of opt.DefElem.arg.List.items) {
+                        if (typeof item?.String?.sval === 'string') {
+                            try {
+                                item.String.sval = rewriteSqlBodyString(item.String.sval, router, result);
+                            }
+                            catch {
+                                // Not parseable standalone (e.g. C symbol names) — leave as-is.
+                            }
+                        }
+                    }
+                }
+            }
+        }
+    };
+}
+/** Rewrite extension references inside a `LANGUAGE sql` body string. */
+function rewriteSqlBodyString(body, router, result) {
+    const stmts = parseSql(body)?.stmts ?? [];
+    if (stmts.length === 0)
+        return body;
+    const visitor = createExtensionVisitor(router, result);
+    const pieces = [];
+    for (const stmt of stmts) {
+        if (!stmt?.stmt)
+            continue;
+        walkSql(stmt.stmt, visitor);
+        pieces.push(Deparser.deparse(stmt.stmt));
+    }
+    return pieces.join(';\n');
+}
+/**
+ * Apply extension routing to a SQL string: parse -> walk -> deparse, including
+ * PL/pgSQL and `LANGUAGE sql` bodies. Returns the rewritten SQL and a summary
+ * of what changed.
+ */
+export function transformExtensions(sql, router, options = {}) {
+    const resolved = ExtensionRouter.from(router, options);
+    const result = createExtensionResult();
+    const out = transformSync(sql, (ctx) => {
+        const stmts = ctx.sql?.stmts ?? [];
+        const visitor = createExtensionVisitor(resolved, result);
+        for (const stmt of stmts) {
+            if (stmt?.stmt)
+                walkSql(stmt.stmt, visitor);
+        }
+        if (resolved.hasSymbolRoutes()) {
+            for (const fn of ctx.functions ?? []) {
+                if (fn.plpgsql?.hydrated) {
+                    walkPlpgsql(fn.plpgsql.hydrated, {}, {
+                        walkSqlExpressions: true,
+                        sqlVisitor: visitor
+                    });
+                }
+            }
+        }
+    }, { hydrate: true, pretty: true });
+    return { sql: out, result };
+}

package/esm/facts.js

@@ -13,6 +13,7 @@ const SECURITY_TAGS = new Set([
 ]);
 const KIND_BY_TAG = {
     CreateSchemaStmt: 'schema',
+    CreateExtensionStmt: 'extension',
     CreateStmt: 'table',
     ViewStmt: 'view',
     IndexStmt: 'index',
@@ -37,6 +38,23 @@ const KIND_BY_TAG = {
 function qn(schema, name) {
     return { schema: schema ?? null, name };
 }
+/**
+ * Read the `SCHEMA <name>` clause of a `CreateExtensionStmt` from its options
+ * (`{ DefElem: { defname: 'schema', arg: { String: { sval } } } }`), or `null`
+ * when the statement specifies no schema.
+ */
+function extensionSchemaOption(options) {
+    if (!Array.isArray(options))
+        return null;
+    for (const opt of options) {
+        const def = opt?.DefElem;
+        if (def?.defname === 'schema') {
+            const sval = def.arg?.String?.sval;
+            return typeof sval === 'string' ? sval : null;
+        }
+    }
+    return null;
+}
 function nameListToQualified(names) {
     if (!Array.isArray(names) || names.length === 0)
         return null;
@@ -142,6 +160,14 @@ function classifyOne(nodeTag, node) {
         case 'CreateSchemaStmt':
             facts.creates.push(qn(null, node.schemaname));
             break;
+        case 'CreateExtensionStmt':
+            facts.extension = {
+                name: node.extname,
+                schema: extensionSchemaOption(node.options),
+                action: 'create',
+                ifNotExists: node.if_not_exists === true
+            };
+            break;
         case 'CreateStmt':
         case 'ViewStmt': {
             const rel = nodeTag === 'ViewStmt' ? node.view : node.relation;
@@ -203,6 +229,34 @@ function classifyOne(nodeTag, node) {
                 facts.creates.push(name);
             break;
         }
+        case 'AlterObjectSchemaStmt':
+            // ALTER EXTENSION <name> SET SCHEMA <newschema>. Other object types
+            // (TABLE/TYPE/FUNCTION ... SET SCHEMA) keep their default classification.
+            if (node.objectType === 'OBJECT_EXTENSION') {
+                const name = node.object?.String?.sval;
+                if (typeof name === 'string') {
+                    facts.kind = 'extension';
+                    facts.extension = {
+                        name,
+                        schema: typeof node.newschema === 'string' ? node.newschema : null,
+                        action: 'set_schema'
+                    };
+                }
+            }
+            break;
+        case 'DropStmt':
+            // DROP EXTENSION <name> [, ...]. Extension names are bare String nodes.
+            // Other DROP object types keep their default classification. When
+            // several extensions are dropped in one statement the first names the
+            // fact; the full list stays available via the raw node.
+            if (node.removeType === 'OBJECT_EXTENSION' && Array.isArray(node.objects)) {
+                const name = node.objects[0]?.String?.sval;
+                if (typeof name === 'string') {
+                    facts.kind = 'extension';
+                    facts.extension = { name, schema: null, action: 'drop' };
+                }
+            }
+            break;
         case 'AlterTableStmt': {
             if (node.relation) {
                 facts.creates.push(qn(node.relation.schemaname ?? null, node.relation.relname));

package/esm/index.js

@@ -1,4 +1,8 @@
 export { classifyStatements } from './facts';
+export { COMMON_EXTENSIONS, ExtensionRouter } from './extension-router';
+export { createExtensionResult, createExtensionVisitor, transformExtensions, } from './extension-transform';
+export { RoleRouter } from './role-router';
+export { createRoleResult, createRoleVisitor, transformRoles, } from './role-transform';
 export { collectCreatedObjects, createQualifyVisitor, mergeInventories, qualifyUnqualified, } from './qualify';
 export { SchemaRouter } from './router';
 export { captureAstsFromSql, captureTransformAsts, firstDifference, normalizeParseTree, validateRoundTrip, } from './round-trip';

package/esm/role-router.js

@@ -0,0 +1,62 @@
+/**
+ * Role-name routing for the core transform.
+ *
+ * Two databases can express the *same* access model with *different* role
+ * names — one calls the unauthenticated role `anonymous`, another `anon`; one
+ * calls the privileged role `administrator`, another something else. Portable
+ * SQL must be able to translate role identifiers between these conventions.
+ *
+ * Scope, deliberately narrow: a {@link RoleRouter} only renames role
+ * *identifiers* in the AST positions where a role name legitimately appears
+ * (grants, ownership, policies, default privileges, role membership, role
+ * settings). It does **not** alter role *attributes* (`BYPASSRLS`, `LOGIN`,
+ * ...): two roles that share a name across conventions do not necessarily
+ * share privilege scope, and inventing attribute changes would silently
+ * misrepresent the security model. Privilege-semantics reconciliation is a
+ * downstream, policy-level concern; the router restricts itself to the
+ * deterministic, reversible part — the name.
+ *
+ * Renaming is a pure identifier substitution, so a router is trivially
+ * invertible ({@link RoleRouter.invert}) for bidirectional translation.
+ */
+/** Resolves a target role name for a source role name. */
+export class RoleRouter {
+    map;
+    constructor(routes = {}) {
+        this.map = routes instanceof Map ? new Map(routes) : new Map(Object.entries(routes));
+    }
+    /** Coerce a spec, map, or existing router into a router. */
+    static from(source) {
+        return source instanceof RoleRouter ? source : new RoleRouter(source);
+    }
+    /** Number of configured renames. */
+    get size() {
+        return this.map.size;
+    }
+    /**
+     * Resolve the target name for `role`, or `undefined` when it is not routed
+     * or already at its destination.
+     */
+    resolve(role) {
+        if (!role)
+            return undefined;
+        const target = this.map.get(role);
+        if (target === undefined || target === role)
+            return undefined;
+        return target;
+    }
+    /**
+     * The inverse router (target -> source), for translating in the opposite
+     * direction. Throws if the mapping is not one-to-one.
+     */
+    invert() {
+        const inverted = new Map();
+        for (const [from, to] of this.map) {
+            if (inverted.has(to)) {
+                throw new Error(`RoleRouter.invert: mapping is not one-to-one (two sources map to "${to}")`);
+            }
+            inverted.set(to, from);
+        }
+        return new RoleRouter(inverted);
+    }
+}