Skip to content
← Ecosystem

Structured output that cannot invent names

pg_grammar_guard v0.4.9

A grammar compiled from your live catalog: the model cannot name what does not exist.

It compiles a token-level grammar from the catalog, so a constrained model cannot name a table, a column or a value that does not exist; and it tells you when a grammar you approved stopped describing your database. Not corrected afterwards: unable.

Install

CREATE EXTENSION pg_grammar_guard;

In plain words

It makes it impossible for the AI to invent table or column names that do not exist in your database.

  1. The situation

    You ask the AI to build a query over your data: "show me this customer's invoices".

  2. Without this piece

    It invents a column "email_address" that does not exist. The query fails, or worse: it silently returns nothing and somebody makes a decision from an empty screen.

  3. With this piece

    The AI can only choose among the real names in your database, taken live. It is not corrected afterwards: it cannot write what does not exist. And that list is watched so it stays current.

Why it matters if you decide

  • Fewer AI mistakes about your data, by construction rather than by trust
  • Works with the most widely used AI engines in the industry
  • Honest about its limit: it makes the invented impossible, it does not guarantee the right answer
For the technical team

The problem

Everyone believes structured output stops a model from inventing things. It does not.

A JSON Schema guarantees the JSON parses and that column is a string. It cannot guarantee the string is a column that exists, because a schema document is written once and your catalog changes on every migration. The model returns {"table": "customers", "column": "email_address"}, perfectly valid, and your query fails at runtime, or worse, silently returns nothing.

A grammar constrains form. In the general case form is not truth. But for identifiers form IS truth, because the set of valid names lives in the catalog.

How it works

Compile, hand to the sampler, watch

  1. 01

    grammar_for_json(fields)

    Each field: name, type (enum, integer…), values (catalog_tables, catalog_columns, catalog_enum) and whether it is required. Out comes GBNF.

  2. 02

    Correlated

    catalog_correlated(tables): columns depend on the chosen table. It is larger than the flat grammar, and it stays linear in (table, column) pairs.

  3. 03

    Where it runs

    llama.cpp (grammar), and XGrammar, the default structured generation backend of vLLM, SGLang, TensorRT-LLM and MLC-LLM, which follows the same GBNF specification. Checked: every grammar in the README plus a real catalog compile under both.

  4. 04

    The guard half

    A grammar generated last month, against a schema migrated last week, still constrains and still looks like protection. Since 0.3.0 that half is pg_living_assertions: watch() stores the QUERY (not the spec) and check_grammar() rebuilds it from the live catalog every time, with the age of each verdict.

SQL

Usage

Constrain a subset, not the whole catalog: a grammar listing every table in the database becomes the giant tool schema you were trying to avoid, and it grows with every relation.

psql · pg_grammar_guardsql
CREATE EXTENSION pg_grammar_guard;

SELECT grammar_guard.grammar_for_json(ARRAY[
    ROW('table',  'enum', grammar_guard.catalog_tables(ARRAY['app']), true),
    ROW('column', 'enum', grammar_guard.catalog_columns('app.customers'), true),
    ROW('limit',  'integer', NULL, false)
]::grammar_guard.grammar_field[]);
-- root ::= "{" ws "\"table\"" ws ":" ws f1-table ws "," ... "}"
-- f1-table  ::= "\"app.customers\"" | "\"app.invoices\""
-- f2-column ::= "\"id\"" | "\"tax_id\"" | "\"name\""

-- once, when you are happy with it (it takes the QUERY, not the spec):
SELECT grammar_guard.watch('answer_v1',
    $$select jsonb_build_array(grammar_guard.catalog_correlated(
               ARRAY['public.invoices', 'public.customers']))$$,
    'shipped 2026-09-03');
-- in CI, or from a monitor:
SELECT grammar_guard.check_grammar('answer_v1');   -- holds | broken | erroring | …

What it guarantees

Measured

  • Matrix 11 through 19 green with make installcheck (measured 2026-09-16); 11 and 12 arrived with 0.4.1.
  • The tests with a model (with the grammar, and a control without it) and the grammar sizes on a real catalog are in the repository README.
  • Arrays are always bounded: an unbounded ( ... )* is a loop waiting to happen. Truncating is far less bad than never stopping: a short array is still valid, closed JSON.
  • Pure SQL: no shared library, and it reads only the catalogs.

What it does not do

What it does not do

  • It makes the nonexistent unreachable. It does not make the answer right: a model constrained to your ten real tables will still pick the wrong one of the ten, and this extension will happily emit that. Measured: constrained, it answered "deploy to production" with a real capability that was the wrong one. Well formed, wrong.
  • It does not generate a grammar for SQL itself: enumerating names is the part where the catalog is the only source of truth; parsing SQL is a solved problem that does not need to live in your database.
  • Requires pg_living_assertions (PostgreSQL 11+): that is why 10 is out.
  • Only for closed sets, the ones the catalog knows in full: table names, the columns of a table, an enum's labels. Open ones (file paths, shell commands, free text, arbitrary SQL) go to your validator, always: a grammar built over an open set does not fail loudly, it makes the correct answer unreachable.

For the enterprise

For the enterprise

The piece for teams already using structured output with a model who discovered the schema does not know which columns exist. The grammar comes from the database, and the database watches that it stays true.

  • Compatible with vLLM, SGLang, TensorRT-LLM, MLC-LLM (XGrammar) and llama.cpp
  • One grammar per use case, with the tables that case may touch
  • Dated watching through pg_living_assertions: a deploy gate or a cron job get a real answer

Spec sheet

Version measured
0.4.9 (public image 0.3.6, 2026-11-13)
PostgreSQL
11 through 19 green (installcheck, 2026-09-16)
Depends on
pg_living_assertions (the guard half)
Format
GBNF (llama.cpp, XGrammar)
License
Apache-2.0
Enterprise edition
Included (PostgreSQL 18)
Try it Talk