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. Example
3. Build Instructions
4. Testing
5. Documentation
6. Versions
7. Related Projects
8. Credit

Installation

npm install libpg-query

Example

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

// Async usage (recommended)
const result = await parseQuery('SELECT * FROM users WHERE id = $1');
console.log(result);

// Sync usage
const syncResult = parseQuerySync('SELECT * FROM users WHERE id = $1');
console.log(syncResult);

CommonJS Usage

const { parseQuery, parseQuerySync } = require('libpg-query');

parseQuery('SELECT * FROM users WHERE id = $1').then(console.log);

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)
• Docker (for WASM compilation using Emscripten)
• yarn or npm

Building WASM Artifacts

1. Install dependencies:

   npm install
   # or
   yarn install

2. Build WASM artifacts:

   npm run wasm:build
   # or
   yarn wasm:build

3. Clean WASM build (if needed):

   npm run wasm:clean
   # or
   yarn wasm:clean

4. Rebuild WASM artifacts from scratch:

   npm run wasm:clean && npm run wasm:build
   # or
   yarn wasm:clean && yarn wasm:build

Build Process Details

The WASM build process:

• Uses Docker with 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
# or
yarn 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

Documentation

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);

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

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

Docker permission errors:

• Ensure Docker is running and accessible
• On Linux, you may need to add your user to the docker group

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