Registry / database / trader-pgsql-ast-parser

trader-pgsql-ast-parser

library10.5.10jsnpmunverified

A TypeScript Postgres SQL syntax parser that produces a typed AST (Abstract Syntax Tree) covering common PostgreSQL syntaxes. Current stable version is 10.5.10, released frequently with CI. Key differentiators: works in both Node.js and browser, provides typed ASTs for TypeScript users, includes AST visitors/mappers for traversal and modification, and supports converting AST back to SQL. It does not support PL/pgSQL and may not cover all edge cases. Built primarily for pg-mem, an in-memory PostgreSQL emulator.

database

npm install trader-pgsql-ast-parser

github ↗package ↗homepage ↗

INSTALL

IMPORT

SIG · TRADER-PGSQL-AST-P

trader-pgsql-ast-parser

databasejavascriptv10.5.10

harness data pending

Install & Compatibility

Where this runs

No compatibility data collected yet for this library.

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

parse

✓ import { parse } from 'pgsql-ast-parser'

✗ const { parse } = require('pgsql-ast-parser'); // CJS works but ESM is preferred

ESM and CJS both supported. parse() takes a string and returns Statement[].

parseFirst

✓ import { parseFirst } from 'pgsql-ast-parser'

✗ import parseFirst from 'pgsql-ast-parser'; // parseFirst is a named export, not default

parseFirst returns a single Statement for the first statement in the input.

toSql

✓ import { toSql } from 'pgsql-ast-parser'

✗ const toSql = require('pgsql-ast-parser').toSql; // CJS usage

toSql is an object with methods like .statement() to convert AST back to SQL.

astVisitor

✓ import { astVisitor } from 'pgsql-ast-parser'

astVisitor is a function that creates a visitor to traverse the AST.

astMapper

✓ import { astMapper } from 'pgsql-ast-parser'

astMapper creates a mapper for AST modification.

Statement

✓ import type { Statement } from 'pgsql-ast-parser'

✗ import { Statement } from 'pgsql-ast-parser'; // Statement is a type, use 'import type' for type-only import

Statement is the base type for all AST nodes.

Demonstrates parsing multiple SQL statements, parsing a single statement, converting AST back to SQL, and traversing the AST with a visitor to collect table names.

import { parse, parseFirst, toSql, astVisitor } from 'pgsql-ast-parser'; // Parse multiple statements const ast = parse(`SELECT * FROM users; INSERT INTO logs VALUES ('test');`); console.log(`Parsed ${ast.length} statements`); // Parse a single statement const singleStmt = parseFirst(`SELECT id, name FROM "my_table" WHERE active = true`); console.log('Parsed single statement:', singleStmt.type); // Convert AST back to SQL const sql = toSql.statement(singleStmt); console.log('Reconstructed SQL:', sql); // Use visitor to traverse AST and collect table names const tables = new Set<string>(); const visitor = astVisitor(map => ({ tableRef: t => tables.add(t.name), join: t => map.super().join(t) // call default to continue traversal })); visitor.statement(singleStmt); console.log('Tables used:', [...tables].join(', '));

Debug

Known issues

gotchaThis parser does NOT support PL/pgSQL (procedural language). Trying to parse PL/pgSQL functions or blocks will produce incomplete AST or errors.

fix

Use a specialized PL/pgSQL parser or avoid parsing procedural code. The parser focuses on SQL DML/DDL statements.

affects: *

breakingIn version 10.0.0, the import paths changed from deeply nested (e.g., 'pgsql-ast-parser/lib/ast-visitor') to top-level exports (e.g., 'pgsql-ast-parser'). Old import paths will break.

fix

Update imports to top-level: import { parse } from 'pgsql-ast-parser' instead of 'pgsql-ast-parser/lib/parser'.

affects: <10.0.0

deprecatedThe 'old' parsing API (like parseOld) is deprecated and will be removed in a future version. Only use the standard parse/parseFirst functions.

fix

Replace any calls to parseOld with parse() or parseFirst().

affects: >=9.0.0

gotchaTypeScript types are exported from the main entry point, but they include internal types not meant for public use. Using internal types may break in minor updates.

fix

Only use the public types exported in the package's type definitions (Statement, etc.). Avoid importing from internal paths like 'pgsql-ast-parser/lib/ast-types'.

affects: *

gotchaThe AST produced by parse() is mutable. Modifying it in place may cause unexpected behavior if used with other functions like toSql or astMapper.

fix

Consider deep-cloning the AST before modification using structuredClone or a library like lodash.cloneDeep.

affects: *

Errors

Common errors & fixes

Cannot find module 'pgsql-ast-parser/lib/parser'

Importing from an old internal path that was removed in v10.

fix

Change import to top-level: import { parse } from 'pgsql-ast-parser'

TypeError: statement is not a function

Calling toSql as a function instead of an object method (toSql.statement).

fix

Use toSql.statement(ast) instead of toSql(ast).

SyntaxError: Unexpected token at position X (SQL: ...)

SQL string contains syntax not supported by the parser (e.g., PL/pgSQL, non-SQL statements).

fix

Review SQL for unsupported syntax. Ensure only standard SQL DML/DDL is passed.

TypeScript error: 'Statement' is a type but is used as a value

Using 'import { Statement }' instead of 'import type { Statement }'.

fix

Change to: import type { Statement } from 'pgsql-ast-parser'

Error: parseFirst expects a single statement, but multiple are provided

Using parseFirst on a SQL string with multiple statements (semicolons).

fix

Use parse() to handle multiple statements, or split the string and call parseFirst on each part.

Upgrade

Version history

10.5.10latest on npm

Audit

Dependencies

typescriptoptionalTypeScript types are shipped and strongly recommended for using the parser

Agent activity

15 hits · last 30 days

node