Architecture

A post-parse hook between the parser and the optimizer.

HyperQuery/PG is a 100% PostgreSQL 15+ compatible extension. It registers a post-parse hook that intercepts the parser's output AST — the parse tree — and rewrites it before forwarding to the query optimizer. Your application, ORM, and driver see nothing different.

HyperQuery/PG architecture diagram: SQL Query enters the SQL Parser, the parse tree passes through the HyperQuery/PG post-parse hook which rewrites anti-patterns, then the rewritten tree is forwarded to the Query Optimizer, Executor, and finally Storage/Transaction/IPC layers. — HyperQuery/PG Architecture — post-parse hook intercepts the parse tree before the query optimizer sees it

The hook

What the post-parse hook sees — and what it does.

PostgreSQL exposes a post_parse_analyze_hook that fires after the parser and analyzer have resolved all types and catalog references but before the planner builds a cost model. HyperQuery/PG owns this hook.

hyperquery_pg.c — hook registration

/* Register on extension load */ void _PG_init(void) { /* Chain any existing hook so other extensions still work */ prev_post_parse_hook = post_parse_analyze_hook; post_parse_analyze_hook = hq_post_parse_hook; } static void hq_post_parse_hook(ParseState *pstate, Query *query, ...) { /* 1. Walk the Query parse tree */ /* 2. Match against the rule library */ /* 3. Rewrite matched sub-trees in-place */ /* 4. Log every rewrite with rule name + original SQL */ /* Pass through — modified or unchanged — to the planner */ if (prev_post_parse_hook) prev_post_parse_hook(pstate, query, ...); }

Fully typed AST, not raw SQL

The hook receives a resolved Query struct — all column types, operator OIDs, and catalog references already bound. Rules match on semantics, not text patterns.

In-process, zero-copy

No proxy, no sidecar, no network hop. The rewrite happens inside the same PostgreSQL backend process handling the connection — adding microseconds, not milliseconds.

Chains existing hooks

HyperQuery/PG saves and restores any previously-registered post-parse hook, so it cooperates correctly with other extensions using the same hook point.

Requires PostgreSQL 15+

The post_parse_analyze_hook signature stabilised in PG 15. HyperQuery/PG targets PostgreSQL 14 and later on self-managed instances.

Full pipeline

Where HyperQuery/PG fits in PostgreSQL's internals.

The diagram maps to a standard PostgreSQL query lifecycle. HyperQuery/PG occupies a single, well-defined slot — nothing else in the pipeline is modified.

SQL Parser

↓

Tokenises and parses your SQL into a raw parse tree. Types and catalog OIDs are not yet resolved.

Semantic Analyzer

↓

Resolves column references, casts, and catalog lookups. Produces the fully typed Query struct.

HyperQuery/PG hook

↓

Intercepts here. Walks the Query tree, matches anti-patterns, rewrites sub-trees in-place. Logs every rewrite. Passes the (possibly modified) tree forward.

Query Optimizer

↓

Receives the rewritten tree. Builds cost estimates, chooses join order and access paths — without ever seeing the original anti-pattern.

Query Executor

↓

Executes the optimised plan, reads from Storage/Transaction/IPC as normal.

→ Query Results

Identical rows, identical order — same result the original query would have returned.

Foundations

Grounded in relational algebra and relational calculus.

HyperQuery/PG's rewrite rules are not heuristics or machine-learned patterns. Each one is derived from first principles in relational algebra — the same mathematical foundation that SQL itself is built on.

Relational equivalence, not empirical testing

A rule ships only when its rewrite can be shown — algebraically — to produce the identical relation: same tuples, same ordering. No edge case is left to empirical testing alone.

NULL semantics are part of the proof

SQL's three-valued logic (TRUE / FALSE / UNKNOWN) is one of the most common sources of subtle correctness bugs in query rewrites. Every rule handles NULL behaviour explicitly.

Order preservation

Rewrites that change join order or set operations are proven to preserve the output ORDER BY — including tie-breaking. The planner's freedom to reorder is preserved downstream.

Regression suite per rule

In addition to the algebraic proof, each rule ships with a schema-and-data regression suite that validates identical output across the full range of known edge cases.

Want to see the hook fire on your queries?

Share your Postgres version and a slow query — we'll walk through exactly which rule would intercept it.

Talk to us See the rule catalog