pg_grammar_guard

Overview

Requires pg_living_assertions, despite older README text claiming no dependencies.

Version

Build

You can build the RPM / DEB packages for pg_grammar_guard using pig build:

pig build pkg pg_grammar_guard         # build RPM / DEB packages

Install

You can install pg_grammar_guard directly. First, make sure the PGDG and PIGSTY repositories are added and enabled:

pig repo add pgsql -u          # Add repo and update cache

Install the extension using pig or apt/yum/dnf:

pig install pg_grammar_guard;          # Install for current active PG version

pig ext install -y pg_grammar_guard -v 18  # PG 18
pig ext install -y pg_grammar_guard -v 17  # PG 17
pig ext install -y pg_grammar_guard -v 16  # PG 16
pig ext install -y pg_grammar_guard -v 15  # PG 15
pig ext install -y pg_grammar_guard -v 14  # PG 14

dnf install -y pg_grammar_guard_18       # PG 18
dnf install -y pg_grammar_guard_17       # PG 17
dnf install -y pg_grammar_guard_16       # PG 16
dnf install -y pg_grammar_guard_15       # PG 15
dnf install -y pg_grammar_guard_14       # PG 14

apt install -y postgresql-18-pg-grammar-guard   # PG 18
apt install -y postgresql-17-pg-grammar-guard   # PG 17
apt install -y postgresql-16-pg-grammar-guard   # PG 16
apt install -y postgresql-15-pg-grammar-guard   # PG 15
apt install -y postgresql-14-pg-grammar-guard   # PG 14

Create Extension:

CREATE EXTENSION pg_grammar_guard CASCADE;  -- requires: pg_living_assertions

Usage

Sources:

• PGXN 0.4.1

pg_grammar_guard generates GBNF or JSON Schema from catalog identifiers and detects drift from approved grammars. It is pure SQL, needs no preload and is packaged for PostgreSQL 14–18. Its control file requires pg_living_assertions.

Generate a grammar

CREATE EXTENSION pg_grammar_guard CASCADE;
CREATE TABLE public.grammar_demo (id integer, label text);
SELECT grammar_guard.grammar_for_json(ARRAY[
  ROW('column', 'enum',
      grammar_guard.catalog_columns('public.grammar_demo'), true)
]::grammar_guard.grammar_field[]);

The catalog helpers enumerate actual tables, columns and enum labels. Generation supports nested objects and bounded arrays; open-ended values such as arbitrary SQL or file paths need separate validation.

Detect changes

grammar_guard.watch() stores the query that rebuilds a grammar, and grammar_guard.check_grammar() evaluates it against the live catalog. Results and their age are available through living_assertions.status.

Register baseline SQL only through trusted administrators. A grammar limits valid identifiers; it cannot prove that a selected table, join or answer is semantically correct. Baselines from the old 0.2 series lack the original generating query and require manual re-approval when upgrading.