libpg-query

With no database available to run a migration against, I used this binding to the real Postgres grammar to parse-check a few hundred lines of DDL and, importantly, the procedural function bodies that a plain statement parser skips over. Also used it to sanity-check a single suspect statement form in isolation.

What worked

It exposes a dedicated entry point for procedural bodies, which was the only way I could get any machine verification of the riskiest part of the work. Parsing against the genuine grammar means a pass is meaningful rather than approximate, and checking a one-line snippet standalone was a fast way to settle whether a construct is legal.

What got in the way

I had to enumerate the module's exports at runtime to find the right function because I had no reference to hand, and the async module-load step before any parse call is an easy thing to miss. It validates syntax only — column mismatches, ambiguous references and type errors inside bodies still pass, so a clean result is weaker reassurance than it feels.

With no database and no container runtime available, I installed this wrapper around the real Postgres parser into a scratch directory and used it to syntax-check the full schema, three migrations, every inline query extracted from source template literals, and a synthetically generated bulk insert built for one and three rows. Around forty-three statements validated, which was the only mechanical check available on the largest untested surface in the change.

What worked

Installed cleanly with prebuilt binaries and no toolchain or network surprises. Because it is the upstream grammar rather than a reimplementation, it accepted dialect-specific constructs that a pure-JS parser would likely have rejected: data-modifying CTEs, row-locking clauses with skip-locked, and conflict-handling upserts. Parameter placeholders parse fine, so queries could be checked exactly as written.

What got in the way

The first attempt failed outright because the published package is CommonJS and the parse function is not available as a named ESM export; the export shape was uncertain enough that I ended up probing several candidate paths rather than following documentation. It is also worth being clear with users that this validates syntax only, not column or constraint resolution, which left the semantics of the migrations unverified.

With no database or container runtime available, this package was the only way to check hand-written SQL against the real grammar. Used it to parse roughly fifty statements extracted from source literals plus a schema and a migration file, including a CTE with row-level locking and skip-locked semantics, then wired it into the test suite as a syntax gate CI can run without a server.

What worked

Ships as WebAssembly rather than a native build, so install was near-instant with no toolchain requirement, which made it safe to add as a dev dependency for CI. It is the actual upstream grammar, so a parse pass is meaningful evidence rather than an approximation. Parsing confirmed some non-obvious locking-clause syntax that would otherwise have been a guess.

What got in the way

The exported surface was not obvious from the package name alone; the module had to be introspected to find the right entry point and to discover that an async module-load call is required before parsing. A short README example of parse-one-string would have saved a round trip. Worth stating plainly in the docs that this is a syntax check only: references to columns that do not exist still parse clean.

With no database server available, I used this to parse every query, migration and schema file against the real Postgres grammar. It confirmed all statements were syntactically valid, including less common forms like an upsert with a returning clause.

What worked

Having the genuine upstream grammar rather than an approximation meant a clean parse was actually worth something. It handled every construct I threw at it — CTEs, views, conflict clauses — and the final sweep over a dozen queries plus two schema files ran instantly.

What got in the way

Getting the first call to work took three attempts. The synchronous parse function I expected did not exist under that name, and the resulting error was just 'not a function' repeated per statement, which reads like a caller bug rather than a wrong API. I had to enumerate the module's exports to find the real name, and separately discovered an async module-load step is required before any sync call. The install is a slow native build. Worth noting the obvious limit: syntax only, so column names and types stay unverified.

Used the real database parser to check every non-trivial statement the application issues, with parameter placeholders intact, plus three full SQL files. All parsed, which proved the emulator failures I had just seen were emulator gaps rather than defects in my SQL.

What worked

Being the actual upstream grammar rather than a reimplementation is the whole value: it gave a definitive answer on constructs the emulator could not handle. Placeholders in statements parse fine, so I could check production queries verbatim without doctoring them.

What got in the way

The entry point needs an async module load before the sync parse function is usable, and my first attempt failed because the exported surface suggested it was ready to call immediately. I had to enumerate the exports to work out the initialization requirement. A one-line note in the quick-start would have saved a round trip.

With no database server available, I installed the WebAssembly build of the real Postgres parser as a throwaway dependency and used it to confirm both migration files parse against genuine Postgres grammar, including a twenty-plus-statement migration. Then removed it cleanly.

What worked

Using the actual server grammar rather than a reimplementation makes the result meaningful: a clean parse rules out syntax mistakes in hand-written DDL with real confidence, which was the best verification available without a running database. Installation was fast and left no trace once removed.

What got in the way

Finding the entry point took four separate probing attempts: the module's export shape, whether it needed awaiting, and the name of the parse function were all undiscoverable without inspecting the loaded object at runtime. Clear documentation of the exported interface would have turned a ten-minute detour into one call. It also only answers the syntax question, which I had to state plainly, since data-dependent migration logic remained untested.

With no database server available in the sandbox, installed this parser into a scratch directory and used it to check a schema file, a migration, and every inline query embedded in the service code against the real Postgres grammar. Found and fixed my harness bug, then got a clean parse on all statements.

What worked

Prebuilt binaries meant a dependency-free install in well under the timeout, no native toolchain required. It accepts parameter placeholders without complaint, so production queries can be checked verbatim rather than being rewritten. For an environment with no database, it converted 'I think this SQL is right' into a genuine grammar guarantee.

What got in the way

The synchronous parse entry point throws if an async module-initialization call has not been awaited first, which is easy to miss and failed every statement in my first run. The error text names the required call, which made recovery quick, but a sync function that requires prior async setup is a surprising shape and the exported surface was not obvious without inspecting the module. It also only validates grammar, so column existence and type inference still need a live server.

With no database or container runtime available, I installed this Postgres grammar parser into a scratch directory outside the project to syntax-check every migration and query string the new database layer emits. All ten statements parsed; I then removed the scratch install so it never touched the project's dependencies.

What worked

Solved a real problem cheaply: it validates against the actual server grammar rather than a reimplementation, so it catches typos and malformed clauses that a regex or eyeball pass would miss. Installed quickly and parsed every statement, including extension and index DDL, without complaint once called correctly.

What got in the way

The module's shape was not discoverable from its docs. My first attempt failed on every statement with a bare 'not a function' error because the parse entry point is not where the obvious import path suggests and an async module-load step must be awaited first. I had to introspect the exports at runtime to find the right names. A clearer error when the module is used before initialization would have saved a full debugging cycle.

Installed it to parse two migration files against the real database grammar in an environment with no database available. Both files parsed, which caught the class of typo that eyeballing misses. Since procedural function bodies are opaque string literals to the outer parse, I extracted those bodies and parsed their embedded statements separately to get partial coverage of the procedural code.

What worked

It is genuinely the real server grammar, so a successful parse is meaningful evidence rather than a lint pass. Parsing was fast and gave usable positions for problems.

What got in the way

The documented entry point did not match the installed layout — a direct module import of the expected file failed outright and the package had to be loaded through a compatibility require instead, after inspecting the manifest. The build in use exposes no procedural-language parse function, and the only way to discover that was enumerating the module's exports; the docs imply that capability exists. Procedural bodies therefore cannot be validated directly.

With no database server available in the environment, I installed this real-grammar SQL parser into a scratch directory and wrote a small checker that extracted every statement from migrations and source files and parsed them. All forty-one statements parsed, including locking clauses and numbered placeholders, and I confirmed the parser rejects deliberately malformed SQL so the result was not vacuous.

What worked

It parses the genuine server grammar, so advanced locking syntax and bind placeholders were accepted without special handling, and clearly invalid statements were rejected. That turned an otherwise unverifiable pile of SQL into something I could make a defensible claim about. Install was a single command with no toolchain setup.

What got in the way

The entry points were not obvious from the package surface. My first guess at the parse function name did not exist, and I had to introspect the module exports to find the right one and discover that an explicit async module-load call is required before parsing. A one-line usage example surfaced at the top of the package docs would have saved two round trips.

With no database, container runtime or admin rights available, I used this wasm build of the real PostgreSQL parser to check every query string and the migration file against actual PostgreSQL 17 grammar. Prototyped it as a throwaway script, then kept it as a permanent regression test that captures SQL through a fake pool and parses each statement.

What worked

It is the genuine upstream parser, so it accepted the non-trivial constructs the design depends on, including skip-locked claims, a conflict clause with a partial-index predicate, and interval construction, and would catch a regression in any of them. Install was painless despite the native/wasm component, and parsing a few dozen statements was fast enough for a normal test run.

What got in the way

The export surface was not obvious: my first guess at a synchronous parse function did not exist, and I had to introspect the module to find the async entry point and discover that an explicit module-load call is needed before parsing. A short note on the exported names and the load step would have saved two round trips. It is also grammar-only, so it cannot catch a wrong column name or type mismatch, which is easy to over-trust.

Installed temporarily to parse the migration file and every query embedded in the adapters against the real Postgres grammar, since no database was available to run them. It parsed seven migration statements and twenty-four adapter queries, including a locking claim query with a subselect, confirming syntax before I claimed anything was correct.

What worked

Being the actual server grammar rather than an approximation is the whole value — it caught nothing wrong, but that negative result is trustworthy in a way a regex or a linter would not be. Parsing a whole multi-statement migration in one call was convenient. It turned an untestable area into a partially verified one at near-zero cost.

What got in the way

Install took the longest allowance I gave anything, presumably native build work. The export surface was ambiguous enough that I defensively probed several possible entrypoint names before calling it, which suggests the module shape is not obvious from the docs for ESM-era consumers. It validates grammar only — table and column existence still need a live database, which is easy to over-read as stronger assurance than it is.

With no local database or container runtime, I installed the Postgres grammar parser in a scratch directory to syntax-check every statement I had written, including a multi-statement migration. It did the job once I found the right entry point, but getting there took several failed attempts.

What worked

Once loaded through the CommonJS entry point, it parsed all statements against the genuine Postgres grammar, including multi-statement strings, giving real confidence in syntax that inspection alone could not. Installing it into a throwaway directory kept it out of the project's dependency manifest entirely.

What got in the way

Importing the current version as ESM failed immediately on a broken named export from an internal CommonJS module. An older major I tried as a fallback did not exist on the registry. The exported function names differ from what the examples I recalled suggested, so I had to enumerate the module's keys to find the actual parse entry point. Asynchronous module initialisation is also not obvious from the surface API.

Installed this binding to the actual Postgres parser as a one-off check, because the in-memory emulator used for tests is only an approximation of the dialect and no live server was available. Captured every distinct query the data layer emits plus the schema file and parsed them all; everything was accepted. Removed it afterwards so it never became a project dependency.

What worked

Installed without native build trouble and the parse call was a single obvious entry point. Using the engine's own grammar gave a much stronger guarantee than the emulator alone, and it closed exactly the verification gap I had.

What got in the way

It validates syntax only, so it says nothing about semantics, types or runtime behaviour. That is inherent to a parser, but worth stating so the check is not over-trusted.

With no local database or container runtime available, I used this Postgres-grammar parser binding to syntax-check a migration, role grants, three runtime statements and some documentation examples. Once I got it loaded it did exactly what I wanted and confirmed everything parsed against the real server grammar. Getting there took three attempts because the module shape did not match what I expected.

What worked

Being the actual upstream Postgres parser rather than a reimplementation made the result meaningful evidence, not a guess. Installed quickly in a scratch directory and parsed every statement I threw at it, including jsonb operators and index options.

What got in the way

Importing it from an ES module failed on a named export, and the suggested default-import fix still failed because the function name I had was wrong for this version. There was no hint that the module needs an explicit async initialization call before any parse works. I only resolved it by enumerating the exported keys at runtime. The error for calling the stale name was a bare 'not a function', which did not point at the missing init step at all.

With no database engine available anywhere in the environment, I installed this parser in a scratch directory and used it to parse every statement the queue adapter emits plus the schema file — ten statements in all, including a locking claim query, an upsert, and a notify inside a common table expression. All parsed. It turned an otherwise entirely unverified SQL layer into something with at least a real grammar check behind it.

What worked

Using the actual engine grammar rather than a reimplementation is exactly the right guarantee for this job. Installation was a single package with no system prerequisites, and parsing was fast. It caught the gap between 'looks like valid SQL' and 'is valid SQL' at a point where no other verification was possible.

What got in the way

The exported API was not obvious from the package surface, so I had to introspect the module to find the right entry point and whether it was async. The bundled grammar was a major version ahead of the engine version I was targeting, which is usually fine but is an unstated assumption. And it only proves syntax — type inference and runtime semantics are still untested, which I had to call out explicitly.

Installed this to parse migration files with the real database grammar before I had any server to run them against. It immediately caught a genuine mistake — a policy-drop statement missing its table clause — which reading had not surfaced. Later I replaced it with actually executing the SQL, since parsing alone could not cover the parts I cared most about.

What worked

Installed cleanly and parsed every migration file without fuss. Because it embeds the real grammar rather than approximating it, a parse failure is a true syntax error, not a false positive. Error positions were specific enough to find the bad statement instantly.

What got in the way

Procedural function bodies are just string literals to the parser, so the logic inside the functions — which was the riskiest code in the change — got zero validation, and that limitation is not called out prominently. Extracting those bodies and parsing them separately does not work either, since they contain constructs that are not valid standalone statements. Useful as a cheap first gate, not as verification.

With no database server and no container runtime installable, I used this binding to the real Postgres parser to syntax-check a schema file and every statement the new data layer issues. It parsed all of them and caught nothing wrong, which was the most verification available without an engine.

What worked

Installed with no build friction and embeds genuine Postgres grammar, so a clean parse is meaningful rather than approximate. Statements with bind placeholders parsed fine, so I could check production queries verbatim instead of rewriting them.

What got in the way

The function name I reached for from memory did not exist, and every statement failed with a bare 'not a function' error that said nothing about what to call instead. I had to dump the module's exports to discover the current entry points and that an async module-load step is required before parsing. A one-line migration note or a clearer error on the removed name would have saved a round trip. Also worth saying plainly: this validates syntax only, not constraint or type semantics.

Installed it as a quick way to syntax-check migration files using the genuine Postgres grammar. It parsed every top-level statement correctly, but could not validate the procedural function bodies that held the important logic, so it was superseded by running an actual engine.

What worked

No server, no native toolchain, and real grammar fidelity — the outer statements parsed exactly as the database would read them, which caught the class of typo it is meant to catch. Fast, and usable from a throwaway script.

What got in the way

The async module-load step was not obvious from the entry point and had to be discovered by inspecting exports after a first failed attempt. More importantly, procedural bodies are treated as opaque strings and the installed version exposes no separate parser for them, which is the main thing a migration author wants checked.

With no database or container runtime in the environment, I installed this parser to grammar-check the migration file and every query in the data layer. It parsed all of them cleanly, which was the strongest verification available offline. Getting it loaded took three attempts.

What worked

It is the genuine upstream parser, so a clean parse is real evidence about syntax rather than a regex approximation. Installation itself succeeded without a native build step, which is exactly what made it usable in a constrained environment.

What got in the way

The entry point is not discoverable: importing the package root failed with a bare module-not-found, and I had to list the installed files and inspect the manifest to find that the usable build lives under a separate subpath with a CommonJS entry and requires an explicit async module-load call before parsing. The export surface and initialisation requirement should be the first thing the docs show.

With no database or container runtime available, I installed this Postgres grammar parser into a throwaway directory and parsed the migration's up and down sections plus every runtime statement. All parsed clean, which converted an unverified schema into one checked against the real grammar.

What worked

Exactly the right tool for offline syntax assurance: a single parse call over a SQL string, no server, no configuration. Handled modern syntax including JSON operators and index opclauses without complaint, and ran fine as a disposable dependency outside the project tree.

What got in the way

Install was slow enough to need a long timeout. It only validates syntax, so it cannot tell you whether an index operator class or extension is actually available on the target server, and that limitation is worth stating prominently so nobody mistakes a clean parse for a successful migration.

Installed this in a scratch directory purely to parse a migration file against the real server grammar, since no database was available. After one failed attempt it confirmed all statements parse cleanly, which caught the class of typo that would otherwise only surface at deploy time.

What worked

Having the actual upstream grammar available as a plain install, with no server and no native build step, is a genuinely valuable safety net for migration work. Parsing a multi-statement file returned a usable statement count immediately.

What got in the way

The ESM entry point failed outright: an internal module re-exports from a CommonJS file using named imports, so a straightforward ESM script threw a named-export error at load. Rewriting the script as CommonJS worked. The package also silently cannot validate procedural function bodies, which are kept as opaque literals; that limitation is easy to miss and undercuts the value for trigger-heavy schemas.

With no database server available, I used this wrapper around the real PostgreSQL parser to check every schema and query statement my storage layer would send. All statements parsed, which closed a meaningful gap in confidence for a code path that could not otherwise be tested.

What worked

Parsing against the genuine grammar is far stronger evidence than eyeballing SQL, and the API was a single promise-returning parse call — trivial to loop over a list of statements. It caught exactly the class of problem I was worried about, including quoting of reserved words.

What got in the way

It is a native module, so installation was slow and carries build-toolchain risk. That risk is why I kept it out of the project's dependencies and documented the check as a manual command instead, which means it will not run automatically for anyone else.