Skip to content

How it works

The agent proposes a statement. PostgreSQL verifies it and decides.

In plain words first, then the detail: the problem, the mechanism step by step, why it lives inside the database, what is measured, and what this site does not claim.

In plain words

Your company wants to use AI with its real data. The question is what happens when the AI gets it wrong.

No jargon. The technical part comes further down, for your team.

  1. Today 01

    You connect an AI assistant to your database

    So it can answer questions and do tasks: update a customer, review orders. It works well. Until one day it misreads an instruction and asks to delete every order of the month.

  2. Without the gate 02

    The database obeys

    It is a valid command from a valid user. The orders are gone. You find out when a customer calls.

  3. With the gate 03

    The database checks before it acts

    It does not run what the AI says: it verifies it, shows exactly what would change (8 orders deleted) and refuses it because it exceeds what is allowed. The legitimate change to one customer goes through. And everything is on record.

One way to see it

Think of how an invoice gets paid in a well-run company: anyone can propose a payment, but nobody executes it alone. It is reviewed, the exact amount is visible, it is approved within a limit, and it goes on the books. That is what the gate does with every instruction an AI gives your database.

What your company gets

  • You can use AI with real data

    Without copying your data elsewhere or trusting the model to "behave". The protection lives in the database itself.

  • Every action is on record

    What the AI proposed, what was approved, what was refused and why. Evidence for an audit, and for sleeping at night.

  • Nothing changes for your team

    It is PostgreSQL, the database you probably already run. Your technical team installs it in an afternoon; there is no new platform to learn.

What it is not

It is not a chatbot and it does not replace your team. It does not decide for you what the AI may do: your team sets the limits and the database enforces them.

The problem

The agent connects. The model hallucinates. The database executes.

  1. 01

    Today an agent reaches PostgreSQL with a role and a connection. From then on, the database cannot tell it from the application.

  2. 02

    Every guarantee lives in the MCP server or in the prompt, outside the database. PostgreSQL never learns what was checked.

  3. 03

    When the model gets it wrong, what reaches the server is valid SQL with valid privileges. And it runs.

It is not a model problem. The decision is in the wrong place.

psql · session of agent "assistant" · public image
assistant=> (agent, max_rows 5, no DDL)
DELETE FROM orders;
ERROR: pg_agent_gate: this session belongs to agent "assistant": it proposes, it does not execute
DETAIL: DELETE does not reach the database from an agent session
SELECT agent_gate.propose('drop table orders', 'fix schema');
{"ok": false, "kind": "ddl", … "checks": [… {"check": "kind_allowed", "detail": "T_DropStmt changes the schema or the server, and this agent is not allowed DDL", "passed": false}], "proposal": 1, …}
SELECT agent_gate.commit(2); -- proposal 2: DELETE FROM orders
{… "rows": [{"after": null, "before": {"id": 1, "total": 1000}}, …], … "reason": "it touched 8 rows, more than this agent may change in one statement", "outcome": "aborted", … "rows_affected": 8, …}
SELECT agent_gate.commit(3); -- proposal 3: UPDATE orders SET total = 999 WHERE id = 1
{… "rows": [{"after": {"id": 1, "total": 999}, "before": {"id": 1, "total": 1000}}], … "outcome": "kept", … "rows_affected": 1, …}

Real output of ghcr.io/latamflows/ygg-pg:0.3.6 (pg_agent_gate 0.4.3), 2026-11-13; the JSON replies are trimmed with "…". The setup is in the try-it section.

How it works

Propose. Verify. Decide.

pg_agent_gate moves the decision into PostgreSQL. An agent does not run SQL: it has seven verbs, and in a session that belongs to it, it cannot do anything else. Not DELETE, not DO, not COPY, not PREPARE.

  1. agent_gate.discover() 01

    What may I touch

    Tables, views and functions the agent has privileges on, with columns, types, keys and constraints. Derived from the live catalog, not from a prompt.

  2. agent_gate.propose() 02

    One statement, nothing runs

    PostgreSQL's own parser, analyzer, rewriter and planner accept it or refuse it. Every check is recorded with its verdict and its reason.

  3. agent_gate.dry_run() 03

    The exact effect, nothing kept

    Runs inside a subtransaction and rolls back: rows touched, before and after of every row, and whether bound assertions would still hold.

  4. agent_gate.commit() 04

    Kept only if every guard agrees

    Verifies again, runs with the agent's own privileges and keeps it. If it touched more rows than its limit or broke an assertion, it is undone. A proposal is committed at most once.

The checks in propose

  • parses
  • single_statement
  • kind_allowed
  • no_writing_cte
  • keeps_its_context
  • no_amplification
  • no_opaque_function
  • resolves

Nothing is reimplemented: each check is PostgreSQL itself.

It is enforced by hooks inside the server. There is no client, driver or protocol path around it: nothing the session types executes, except the seven verbs.

Without the gate / with the gate

Without pg_agent_gate
an ordinary role, the way an agent connects today
database now: customers: 4 · orders: 8
DELETE FROM orders
database now: customers: 4 · orders: 0
DROP TABLE customers CASCADE
database now: customers: TABLE GONE · orders: 8
set_config('app.tenant_id', '2') + SELECT
Iris|iris@TWO.example
Juan|juan@TWO.example
With pg_agent_gate
the same role, registered as an agent (max_rows 5, no DDL)
DELETE FROM orders
ERROR: pg_agent_gate: this session belongs to agent "assistant": it proposes, it does not execute
DROP TABLE customers CASCADE
ERROR: pg_agent_gate: this session belongs to agent "assistant": it proposes, it does not execute
…and the same, PROPOSED through the gate:
propose + commit: DELETE FROM orders
commit: aborted -- it touched 8 rows, more than this agent may change in one statement
propose: DROP TABLE customers
refused at propose -- kind_allowed: T_DropStmt changes the schema or the server, and this agent is not allowed DDL
propose: a read that moves the tenant from inside the statement
refused at propose -- keeps_its_context: set_config() would change, while the proposal runs, a parameter …
database now: customers: 4 · orders: 8
dry_run: UPDATE customers SET email = … WHERE id = 1
"rows": [{"before": {"email": "ana@one.example"}, "after": {"email": "ana@new.example"}}] (nothing kept)
commit
kept, Ana's email is now ana@new.example

What an agent sees

Where an ordinary server hands back a row count after it ran, the gate returns the catalog the agent may touch, every check with its verdict, and the exact before/after of the change, before anything is kept.

psql · session of agent "billing"sql
-- what may I touch? derived from the live catalog and MY privileges
SELECT agent_gate.discover('customers');

-- propose one statement: nothing runs
SELECT agent_gate.propose(
  'update customers set plan = ''pro'' where id = $1::int',
  'upgrade the customer who asked for it',
  ARRAY['1']);
--  {"proposal": 42, "ok": true, "kind": "write", "estimated_rows": 1,
--   "checks": [{"check": "parses",           "passed": true},
--              {"check": "single_statement", "passed": true},
--              {"check": "kind_allowed",     "passed": true},
--              ... no_writing_cte, keeps_its_context, no_amplification, no_opaque_function, resolves]}

-- see the exact effect, then nothing is kept
SELECT agent_gate.dry_run(42);
--  {"outcome": "rolled_back", "rows_affected": 1,
--   "rows": [{"before": {"id": 1, "plan": "free"}, "after": {"id": 1, "plan": "pro"}}]}

-- make it real, if every guard still agrees
SELECT agent_gate.commit(42);
--  {"outcome": "kept", "rows_affected": 1}

No MCP in between

The model writes SQL. No MCP server, no HTTP and no JSON between the agent and your data.

The usual setup puts an MCP server between the model and the database: that server holds the connection, hands the model a list of tools, and runs whatever the model asks. Here that piece does not exist. The agent arrives over psql, a driver or direct SQL: the statement travels over PostgreSQL's own protocol, with no HTTP and no JSON-RPC on the way, and what decides lives inside the database. For a client that only speaks MCP there is a shim, but it is a compatibility layer, not the product.

The usual way

  1. Model
  2. MCP server
  3. PostgreSQL

The data travels as JSON-RPC. The model decides, the server obeys, and the database executes.

With pg_agent_gate

  1. Model
  2. Native SQL
  3. PostgreSQL + the gate

PostgreSQL's own protocol: no HTTP and no JSON. With the model in process (ygg-agent 0.2.0), no HTTP end to end. The model proposes and PostgreSQL decides.

ygg-agent 0.2.0 · Python

The loop between the model and PostgreSQL, in one process

The model writes one statement; the gate verifies it, runs it under the agent's own limits, and records it; the verdict goes back to the model. No MCP server, no tool schema in the model's context, and no JSON between the model and its data. Since 0.2.0 the model can run inside the same process (a GGUF file loaded with llama.cpp): no model server and no HTTP, and the only connection opened is PostgreSQL's. It also talks to any /v1/chat/completions server: llama.cpp, vLLM, Ollama or OpenAI.

ygg-agent on GitHub →

pg_phasevec (0.x preview) · C++ over llama.cpp

The model that reads runs next to the database

The pg_phasevec reference reader loads the model with llama.cpp inside its own process and talks to the database directly: no HTTP and no service in between. Before reading, it proves to the database, by sha256, that the weights it loaded are the ones that were registered.

The reader, in the repo →

pg_grammar_guard · GBNF

The wrong name cannot be written

pg_grammar_guard generates, from the live catalog, a GBNF grammar, which is the llama.cpp format. With it the sampler decides token by token, and a name that does not exist is out of its reach.

pg_grammar_guard on GitHub →

The pipe: what JSON costs

MCP is JSON-RPC, and JSON has no 64-bit integer, no exact decimal and no binary. The gate's guarantee is the same over either path; what changes is the pipe your data travels through.

The same dataNative, PostgreSQL's own protocolForced through JSON
The id 9007199254740993 exact 9007199254740992: a JSON number is an IEEE double
numeric(40,12) exact lost, unless it travels as a string
Binary the bytes, raw base64 text, longer

Reproduce it with make transfer in the pg_agent_gate repo. It uses no real data.

Measured with pg_agent_gate 0.4.0, with the same gate behind both

  • 5x fewer prompt tokens for the agent without MCP than through MCP (24k vs 126k for 13 tasks).
  • 13x faster per task: a median of 14 s against 185 s.

The safety does not come from removing MCP: it comes from the database deciding. Without MCP it is more efficient and the control does not sit in the connector.

If your client only speaks MCP, there is a shim (gated-mcp) that connects as the agent role and has no power of its own: it can only call the gate.

See the run →

Why inside the database

There are four places to put the last word. Only one cannot be bypassed.

Rules in the prompt, a proxy with guardrails, custom middleware, or the database itself. They are not exclusive: the prompt still guides and a proxy can stay. What changes is who decides in the end.

Criterion Rules in the promptProxy or MCP server with guardrailsCustom middlewarepg_agent_gate, inside PostgreSQL
Who enforces the rule? The model, if it remembers A separate process in front of the database Your code The PostgreSQL server, by hooks
Can it be bypassed by connecting another way (psql, a driver)? Yes Yes, if someone connects directly Yes, if someone connects directly No: in the agent’s session SQL does not execute
Does it see the real effect before keeping? No It estimates from outside Depends on what you build Yes: PostgreSQL measures it (rows, before and after)
A record nobody can edit? No The proxy’s logs Whatever you build Append-only in the database; survives pg_dump
Tied to the model or the AI vendor? Yes Partly No No: the agent only needs to speak SQL
What does it cost to run? Tokens on every call One more service to keep up Months of development and upkeep One extension inside PostgreSQL, no other service

The gate’s column comes from the pg_agent_gate README and its test suites. The other three describe the approach in general, not a particular product.

Measured with pg_agent_gate 0.4.0

Every number comes from a public run anyone can re-run.

  • 0/7

    trap tasks broke out with the database deciding; through a popular Postgres MCP server, 4 of 7. Same model, same tasks, a superuser checking what really changed.

    Source →

  • 5 x

    fewer prompt tokens for the agent without MCP than through MCP, with the same gate behind both (24k vs 126k for 13 tasks).

    Source →

  • 13 x

    faster per task without MCP: a median of 14 s against 185 s, on a CPU-only CI runner anyone can re-run.

    Source →

  • 6 s

    median per task for writing one statement and letting the database decide.

    Source →

Every figure was measured with pg_agent_gate 0.4.0, not the current version. Reference run: the CI of the agent-gate-demo repository, on a CPU-only GitHub runner; every figure is tied to its raw data by sha256 in pg-evidence. We found a gap ourselves — a looping model split a refused delete into legal slices — and closed it in 0.4.0: a write budget per agent, on by default.

What we say and what we do not

The product is sold by showing that it works.

  • The public image is a preview

    It runs PostgreSQL 19 release candidate. It is for evaluating the ecosystem, not for production. That is what the Enterprise edition is for.

  • Red Hat: partner, container not certified

    LatamFlows is a Red Hat partner; container certification is the next step. The ygg-pg Enterprise 0.3.1 image (pg_agent_gate 0.4.3) is not certified.

  • Security has limits, and they are written down

    pg_agent_gate documents its threat model and what it does not cover. Read it before you trust it: the gate bounds what the agent names, not its intent.

    Threat model and what it does not cover →
  • No invented customers or numbers

    There are no testimonials, logos or usage figures on this page because we will not make them up. What is here can be verified in the repositories.

    See the repositories →

Contact

Write to us. We will get back to you.

Enterprise edition, security audit or agent-to-database integration: one email with two lines about your case is enough. We answer in English and Spanish.

Email

manu@latamflows.com

A person reads the email. If you would rather write directly, the address is above.

Or tell us here

We only use this to reply to you. No lists, no newsletters.

Who is behind this

Manuel Reyes Bravo

The seven extensions, the image and the contributions to PostgreSQL core are signed by Manuel Reyes Bravo, from Chile. To talk code, repositories or the PostgreSQL lists, his personal email:

Personal email

manuelreyesbravo@gmail.com

Also through GitHub issues: pg_agent_gate/issues

Try it Talk