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.
- The situation
You ask the AI to build a query over your data: "show me this customer's invoices".
- 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.
- 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
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
- 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.
- 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.
- 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.
- 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.
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)
The other pieces of the ecosystem
- pg_agent_gate AI agents on PostgreSQL
- pg_phasevec · preview 0.x Vector memory with provenance
- pg_living_assertions Guarantees with a date
- pg_plan_guard Query plans, watched
- pg_recall_guard Vector index recall
- pg_promise_guard Schema guarantees
- ygg-agent v0.2.0 · PyPI The agent loop on pg_agent_gate, with no MCP: the model writes SQL and the database decides.