libpg-query

The real PostgreSQL parser for Node.js, powered by WebAssembly (WASM) for true cross-platform compatibility.

A WASM-based PostgreSQL query parser that provides the same functionality as the native PostgreSQL parser without requiring native compilation or platform-specific binaries. Primarily used for the node.js parser and deparser pgsql-parser.

Table of Contents

1. Installation
2. Usage
3. Build Instructions
4. Testing
5. Versions
6. Related Projects
7. Credit

Installation

npm install libpg-query

Usage

parseQuery(sql: string): Promise<ParseResult[]>

Parses the SQL and returns a Promise for the parse tree. May reject with a parse error.

import { parseQuery } from 'libpg-query';

const result = await parseQuery('SELECT * FROM users WHERE active = true');
// Returns: ParseResult[] - array of parsed query objects

parseQuerySync(sql: string): ParseResult[]

Synchronous version that returns the parse tree directly. May throw a parse error.

import { parseQuerySync } from 'libpg-query';

const result = parseQuerySync('SELECT * FROM users WHERE active = true');
// Returns: ParseResult[] - array of parsed query objects

parsePlPgSQL(funcsSql: string): Promise<ParseResult>

Parses the contents of a PL/pgSQL function from a CREATE FUNCTION declaration. Returns a Promise for the parse tree.

import { parsePlPgSQL } from 'libpg-query';

const functionSql = `
CREATE FUNCTION get_user_count() RETURNS integer AS $$
BEGIN
    RETURN (SELECT COUNT(*) FROM users);
END;
$$ LANGUAGE plpgsql;
`;

const result = await parsePlPgSQL(functionSql);

parsePlPgSQLSync(funcsSql: string): ParseResult

Synchronous version of PL/pgSQL parsing.

import { parsePlPgSQLSync } from 'libpg-query';

const result = parsePlPgSQLSync(functionSql);

deparse(parseTree: ParseResult): Promise<string>

Converts a parse tree back to SQL string. Returns a Promise for the SQL string.

import { parseQuery, deparse } from 'libpg-query';

const parseTree = await parseQuery('SELECT * FROM users WHERE active = true');
const sql = await deparse(parseTree[0]);
// Returns: string - reconstructed SQL query

deparseSync(parseTree: ParseResult): string

Synchronous version that converts a parse tree back to SQL string directly.

import { parseQuerySync, deparseSync } from 'libpg-query';

const parseTree = parseQuerySync('SELECT * FROM users WHERE active = true');
const sql = deparseSync(parseTree[0]);
// Returns: string - reconstructed SQL query

fingerprint(sql: string): Promise<string>

Generates a unique fingerprint for a SQL query that can be used for query identification and caching. Returns a Promise for a 16-character fingerprint string.

import { fingerprint } from 'libpg-query';

const fp = await fingerprint('SELECT * FROM users WHERE active = $1');
// Returns: string - unique 16-character fingerprint (e.g., "50fde20626009aba")

fingerprintSync(sql: string): string

Synchronous version that generates a unique fingerprint for a SQL query directly.

import { fingerprintSync } from 'libpg-query';

const fp = fingerprintSync('SELECT * FROM users WHERE active = $1');
// Returns: string - unique 16-character fingerprint

normalize(sql: string): Promise<string>

Normalizes a SQL query by removing comments, standardizing whitespace, and converting to a canonical form. Returns a Promise for the normalized SQL string.

import { normalize } from 'libpg-query';

const normalized = await normalize('SELECT * FROM users WHERE active = true');
// Returns: string - normalized SQL query

normalizeSync(sql: string): string

Synchronous version that normalizes a SQL query directly.

import { normalizeSync } from 'libpg-query';

const normalized = normalizeSync('SELECT * FROM users WHERE active = true');
// Returns: string - normalized SQL query

Initialization

The library provides both async and sync methods. Async methods handle initialization automatically, while sync methods require explicit initialization.

Async Methods (Recommended)

Async methods handle initialization automatically and are always safe to use:

import { parseQuery, deparse } from 'libpg-query';

// These handle initialization automatically
const result = await parseQuery('SELECT * FROM users');
const sql = await deparse(result[0]);

Sync Methods

Sync methods require explicit initialization using loadModule():

import { loadModule, parseQuerySync } from 'libpg-query';

// Initialize first
await loadModule();

// Now safe to use sync methods
const result = parseQuerySync('SELECT * FROM users');

loadModule(): Promise<void>

Explicitly initializes the WASM module. Required before using any sync methods.

import { loadModule, parseQuerySync } from 'libpg-query';

// Initialize before using sync methods
await loadModule();
const result = parseQuerySync('SELECT * FROM users');

Note: We recommend using async methods as they handle initialization automatically. Use sync methods only when necessary, and always call loadModule() first.

Type Definitions

interface ParseResult {
  version: number;
  stmts: Statement[];
}

interface Statement {
  stmt_type: string;
  stmt_len: number;
  stmt_location: number;
  query: string;
}

Note: The return value is an array, as multiple queries may be provided in a single string (semicolon-delimited, as PostgreSQL expects).

Build Instructions

This package uses a WASM-only build system for true cross-platform compatibility without native compilation dependencies.

Prerequisites

• Node.js (version 16 or higher recommended)

Building WASM Artifacts

1. Install dependencies:

   npm install

2. Build WASM artifacts:

   npm run wasm:build

3. Clean WASM build (if needed):

   npm run wasm:clean

4. Rebuild WASM artifacts from scratch:

   npm run wasm:clean && npm run wasm:build

Build Process Details

The WASM build process:

• Uses Emscripten SDK for compilation
• Compiles C wrapper code to WebAssembly
• Generates wasm/libpg-query.js and wasm/libpg-query.wasm files
• No native compilation or node-gyp dependencies required

Testing

Running Tests

npm test

Test Requirements

• WASM artifacts must be built before running tests
• If tests fail with "fetch failed" errors, rebuild WASM artifacts:

  npm run wasm:clean && npm run wasm:build && npm test

Versions

Our latest is built with 17-latest branch from libpg_query

| PG Major Version | libpg_query | Branch | npm |--------------------------|-------------|------------------------------------------------------------------------------------------------|---------| | 17 | 17-latest | 17-latest | [email protected] | 16 | 16-latest | 16-latest | [email protected] | 15 | 15-latest | 15-latest | [email protected] | 14 | 14-latest | 14-latest | [email protected] | 13 | 13-latest | 13-latest | [email protected] | 12 | (n/a) | | | 11 | (n/a) | | | 10 | 10-latest | | @1.3.1 (tree) |

Troubleshooting

Common Issues

"fetch failed" errors during tests:

• This indicates stale or missing WASM artifacts
• Solution: npm run wasm:clean && npm run wasm:build

"WASM module not initialized" errors:

• Ensure you call an async method first to initialize the WASM module
• Or use the async versions of methods which handle initialization automatically

Build environment issues:

• Ensure Emscripten SDK is properly installed and configured
• Check that all required build dependencies are available

Build Artifacts

The build process generates these files:

• wasm/libpg-query.js - Emscripten-generated JavaScript loader
• wasm/libpg-query.wasm - WebAssembly binary
• wasm/index.js - ES module exports
• wasm/index.cjs - CommonJS exports with sync wrappers

Related Projects

• libpg_query
• pgsql-parser
• pg_query
• pg_query.go

Credit

This is based on the output of libpg_query. This wraps the static library output and links it into a node module for use in js.

All credit for the hard problems goes to Lukas Fittl.

Additional thanks for the original Node.js integration work by Ethan Resnick.

Original Code and License