libpg-query

The real PostgreSQL parser, exposed for nodejs.

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

const parser = require('libpg-query');
parser.parseQuery('select 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

Expected Test Output

All tests should pass:

  Queries
    Sync Parsing
      ✓ should return a single-item parse result for common queries
      ✓ should support parsing multiple queries
      ✓ should not parse a bogus query
    Async parsing
      ✓ should return a promise resolving to same result
      ✓ should reject on bogus queries
    Deparsing
      ✓ async function should return a promise resolving to same SQL
      ✓ sync function should return a same SQL
      [... more tests ...]

  18 passing (70ms)

Documentation

query.parseQuery(sql)/parseQuerySync

Parses the sql and returns a Promise for the parse tree (or returns the parse tree directly in the sync version). May reject with/throw a parse error.

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

query.parsePlPgSQL(funcsSql)/query.parsePlPgSQLSync(funcsSql)

Parses the contents of a PL/PGSql function, from a CREATE FUNCTION declaration, and returns a Promise for the parse tree (or returns the parse tree directly in the sync version). May reject with/throw a parse error.

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 node binding Ethan Resnick.

Original Code and License