pgsql-parse

Comment and whitespace preserving PostgreSQL parser. A drop-in enhancement for pgsql-parser that preserves SQL comments (-- line and /* */ block) and vertical whitespace (blank lines) through parse-deparse round trips.

Installation

npm install pgsql-parse

Features

• Comment Preservation -- Retains -- line comments and /* */ block comments through parse-deparse cycles
• Vertical Whitespace -- Preserves blank lines between statements for readable output
• Idempotent Round-Trips -- parse -> deparse -> parse -> deparse produces identical output
• Drop-in API -- Re-exports parse, parseSync, deparse, deparseSync, loadModule from pgsql-parser
• Synthetic AST Nodes -- RawComment and RawWhitespace nodes interleaved into the stmts array by byte position

How It Works

1. A pure TypeScript scanner extracts comment and whitespace tokens with byte positions from the raw SQL text
2. Enhanced parse/parseSync call the standard libpg-query parser, then interleave synthetic RawComment and RawWhitespace nodes into the stmts array based on byte position
3. deparseEnhanced() dispatches on node type -- real RawStmt entries go through the standard deparser, while synthetic nodes emit their comment text or blank lines directly

API

Enhanced Parse

import { parse, parseSync, deparseEnhanced, loadModule } from 'pgsql-parse';

// Async (handles initialization automatically)
const result = await parse(`
-- Create users table
CREATE TABLE users (id serial PRIMARY KEY);

-- Create posts table
CREATE TABLE posts (id serial PRIMARY KEY);
`);

// result.stmts contains RawComment, RawWhitespace, and RawStmt nodes
const sql = deparseEnhanced(result);
// Output preserves comments and blank lines

Sync Methods

import { parseSync, deparseEnhanced, loadModule } from 'pgsql-parse';

await loadModule();

const result = parseSync('-- comment\nSELECT 1;');
const sql = deparseEnhanced(result);

Type Guards

import { isRawComment, isRawWhitespace, isRawStmt } from 'pgsql-parse';

for (const stmt of result.stmts) {
  if (isRawComment(stmt)) {
    console.log('Comment:', stmt.RawComment.text);
  } else if (isRawWhitespace(stmt)) {
    console.log('Blank lines:', stmt.RawWhitespace.lines);
  } else if (isRawStmt(stmt)) {
    console.log('Statement:', stmt);
  }
}

Credits

Built on the excellent work of several contributors:

• Dan Lynch -- official maintainer since 2018 and architect of the current implementation
• Lukas Fittl for libpg_query -- the core PostgreSQL parser that powers this project

🛠 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.