@pgsql/transform

@pgsql/transform

AST-based SQL transformation, qualification, classification, and dependency-closure analysis for PostgreSQL. Works on plain SQL and inside PL/pgSQL function bodies (via plpgsql-parser hydration) — no regexes.

Looking for the PG13→17/18 version-upgrade AST transformer previously published under this name? It now lives at @pgsql/transform-ast.

Installation

npm install @pgsql/transform

The parser runs on a WASM build of the real PostgreSQL parser; call loadModule() from plpgsql-parser once before using any synchronous API.

Features

transformSql — schema-name rewriting

Rewrite schema names everywhere they can appear (DDL, DML, function bodies, trigger definitions, grants, policies, comments, type casts, string-embedded types inside PL/pgSQL, ...):

import { loadModule } from 'plpgsql-parser';
import { transformSql } from '@pgsql/transform';

await loadModule();
const mapping = new Map([['my-schema', 'my_schema']]);
const { sql } = transformSql(inputSql, mapping);

classifyStatements — per-statement AST facts

import { classifyStatements } from '@pgsql/transform';

const facts = classifyStatements(sql);
// per statement: kind (schema|table|view|index|type|function|trigger|policy|grant|...),
// creates, references (incl. inside PL/pgSQL bodies), referencedSchemas, roles,
// fkTargets, securityRelevant, securityDefiner, dynamicSql

qualifyUnqualified — add schema qualification

Qualify unqualified object references against an inventory of known objects, with multi-schema routing support.

Round-trip validation

normalizeTree / cleanTree / validateRoundTrip — dependency-free AST normalization and mutation-aware parse→deparse→re-parse validation.

Relationship to @pgsql/traverse

This package owns policy, not traversal. Every entry point above parses once, then drives walk from @pgsql/traverse over the parsed script — statements and hydrated PL/pgSQL bodies alike — with a visitor built here:

Concern	Lives here
Which schema/role/extension a name maps to	SchemaRouter, RoleRouter, extension routes
What counts as a reference, a creation, a security-relevant statement	classifyStatements
When an unqualified name should be qualified	qualifyUnqualified
Whether the rewritten SQL still parses to the same tree	validateRoundTrip
How to reach every node of a SQL or PL/pgSQL AST	@pgsql/traverse

So mapping logic never moves into the walker, and traversal logic never moves in here. Some passes keep per-statement state (CTE names in qualifyUnqualified, per-statement facts in classifyStatements) and drive the walkSqlAst / walkPlpgsqlAst primitives directly with a visitor per statement.

Consequence for contributors: __fixtures__/output/ is the regression gate for traversal changes made anywhere in the ecosystem. A walker change that alters these golden files is a behavior change, not a refactor.

Scripts

• npm run fixtures — regenerate __fixtures__/output/ golden files from __fixtures__/input/
• npm run scan-corpus <dir> [dir...] — audit node-type coverage over a SQL corpus

🛠 Built by the Constructive team — creators of modular Postgres tooling for secure, composable backends. If you like our work, contribute on GitHub.

Related

• pgpm: A Postgres Package Manager that brings modular development to PostgreSQL with reusable packages, deterministic migrations, recursive dependency resolution, and tag-aware versioning.
• pgsql-test: Instant, isolated PostgreSQL databases for each test with automatic transaction rollbacks, context switching, and clean seeding for fast, reliable database testing.
• pgsql-seed: PostgreSQL seeding utilities for CSV, JSON, SQL data loading, and pgpm deployment.
• pgsql-parser: The real PostgreSQL parser for Node.js, providing symmetric parsing and deparsing of SQL statements with actual PostgreSQL parser integration.
• pgsql-deparser: A streamlined tool designed for converting PostgreSQL ASTs back into SQL queries, focusing solely on deparser functionality to complement pgsql-parser.
• @pgsql/parser: Multi-version PostgreSQL parser with dynamic version selection at runtime, supporting PostgreSQL 15, 16, and 17 in a single package.
• @pgsql/types: Offers TypeScript type definitions for PostgreSQL AST nodes, facilitating type-safe construction, analysis, and manipulation of ASTs.
• @pgsql/enums: Provides TypeScript enum definitions for PostgreSQL constants, enabling type-safe usage of PostgreSQL enums and constants in your applications.
• @pgsql/utils: A comprehensive utility library for PostgreSQL, offering type-safe AST node creation and enum value conversions, simplifying the construction and manipulation of PostgreSQL ASTs.
• @pgsql/traverse: PostgreSQL AST traversal utilities for pgsql-parser, providing a visitor pattern for traversing PostgreSQL Abstract Syntax Tree nodes, similar to Babel's traverse functionality but specifically designed for PostgreSQL AST structures.
• pg-proto-parser: A TypeScript tool that parses PostgreSQL Protocol Buffers definitions to generate TypeScript interfaces, utility functions, and JSON mappings for enums.
• libpg-query: The real PostgreSQL parser exposed for Node.js, used primarily in pgsql-parser for parsing and deparsing SQL queries.

Disclaimer

AS DESCRIBED IN THE LICENSES, THE SOFTWARE IS PROVIDED "AS IS", AT YOUR OWN RISK, AND WITHOUT WARRANTIES OF ANY KIND.

No developer or entity involved in creating Software will be liable for any claims or damages whatsoever associated with your use, inability to use, or your interaction with other users of the Software code or Software CLI, including any direct, indirect, incidental, special, exemplary, punitive or consequential damages, or loss of profits, cryptocurrencies, tokens, or anything else of value.