pgsql-ast-parser 12.x

Complete instructions

Verified against pgsql-ast-parser@12.0.2 on 2026-09-08. 5 of 5 examples executed.

pgsql-ast-parser

Scope

This skill targets pgsql-ast-parser ^12.0.0 (resolved research version 12.0.2). It is a PostgreSQL AST parser usable from Node or the browser. It does not support PL/pgSQL and may not cover unusual PostgreSQL syntax.

The package is an ordinary library: examples run directly with Bun and do not need a test runner, framework globals, a database, a network, or a filesystem.

Parse statements

Import parse for potentially multiple statements and parseFirst when exactly one statement is expected. parse returns Statement[]; parseFirst returns a Statement.

import assert from 'node:assert/strict';
import { parse, parseFirst } from 'pgsql-ast-parser';

const statements = parse(`BEGIN TRANSACTION;
  INSERT INTO my_table VALUES (1, 'two');`);
assert.equal(statements.length, 2);

const statement = parseFirst('SELECT * FROM "my_table";');
assert.ok(statement);
assert.equal(statement.type, 'select');

Do not assume that examples from older major versions describe the current AST shape. In particular, historical release notes describe an old ALTER TABLE shape where change became changes, and an older INSERT shape with values or select that was later replaced by a single insert property. Those notes are not a v12 migration guide; the available v12 research exposes no v11-to-v12 breaking-change list. Inspect the parsed v12 AST or use the current types rather than copying an old shape.

Generate SQL

Use toSql.statement(ast) for a complete statement. toSql also exposes generators for AST subparts.

import assert from 'node:assert/strict';
import { parseFirst, toSql } from 'pgsql-ast-parser';

const ast = parseFirst('SELECT * FROM users WHERE id = 1');
const sql = toSql.statement(ast);

assert.equal(typeof sql, 'string');
assert.match(sql.toLowerCase(), /select/);
assert.match(sql.toLowerCase(), /users/);

Visit an AST

Create a visitor with astVisitor. Visitor callbacks can inspect nodes. If a callback wants traversal to continue through a node, call the corresponding method on map.super().

import assert from 'node:assert/strict';
import { astVisitor, parseFirst } from 'pgsql-ast-parser';

const tables = new Set<string>();
let joins = 0;

const visitor = astVisitor(map => ({
  tableRef: (table: { name: string }) => {
    tables.add(table.name);
  },
  join: (join: unknown) => {
    joins++;
    map.super().join(join as never);
  }
}));

visitor.statement(parseFirst('SELECT * FROM ta LEFT JOIN tb ON ta.id = tb.id'));

assert.deepEqual([...tables].sort(), ['ta', 'tb']);
assert.equal(joins, 1);

Transform an AST

Create a mapper with astMapper. Return a replacement node from a callback. Delegate unchanged nodes to map.super(). A mapper callback may return null to remove a node; consequently, a mapped statement can be null.

import assert from 'node:assert/strict';
import { astMapper, parseFirst, toSql } from 'pgsql-ast-parser';

const mapper = astMapper(map => ({
  tableRef: (table: { name: string }) => {
    if (table.name === 'foo') return { ...table, name: 'bar' };
    return map.super().tableRef(table as never);
  }
}));

const modified = mapper.statement(parseFirst('SELECT * FROM foo'));
assert.ok(modified);
assert.match(toSql.statement(modified).toLowerCase(), /bar/);
assert.doesNotMatch(toSql.statement(modified).toLowerCase(), /from foo/);

Locations and comments

The documented API includes parseWithComments(), locationOf(node), and location tracking through parse(sql, { locationTracking: true }). Use location tracking when source positions are needed; do not expect locations from an ordinary parse.

import assert from 'node:assert/strict';
import { locationOf, parse } from 'pgsql-ast-parser';

const statements = parse('SELECT 1', { locationTracking: true });
assert.equal(statements.length, 1);
const location = locationOf(statements[0]);
assert.ok(location);

parseWithComments() is the separate documented entry point when comments must be retained or associated with parsing. The available research does not specify its exact return shape, so inspect the package’s exported types before depending on comment-node fields.

Literal and utility helpers

The package also documents parseArrayLiteral(), parseGeometricLiteral(), parseIntervalLiteral(), assignChanged(), and arrayNilMap(). They are library helpers and can be imported directly; their detailed signatures and return shapes are not covered by the available research, so consult the installed v12 TypeScript declarations before using them.

Deno

The research documents a generated Deno module import:

import { /* imports */ } from 'https://deno.land/x/pgsql_ast_parser/mod.ts';

For Node, browser, and Bun usage, import from the npm package name as shown above. Repository build scripts, webpack configuration, test commands, and Deno-generation scripts are development machinery, not consumer requirements.

Does not cover

• PL/pgSQL parsing.
• A complete PostgreSQL-syntax compatibility matrix or unusual/funky syntax.
• A v11-to-v12 migration guide; none was documented in the researched release material.
• Exact AST schemas for every statement and expression.
• Exact signatures or return shapes for parseWithComments(), parseArrayLiteral(), parseGeometricLiteral(), parseIntervalLiteral(), assignChanged(), and arrayNilMap().
• Database execution, SQL validation, formatting guarantees, or a package-owned CLI/runner.