B0yko/pgwarden

How it works  · 
Results  · 
Limitations  · 
Docs
pgwarden is an MCP gateway that lets Claude, ChatGPT, Cursor or any MCP client query
Postgres as the person asking. People sign in through your OIDC provider; the gateway
connects as their own Postgres role, and the database decides what they see through your
grants, row-level security and masking views. Reads are read-only by construction, writes
wait for a named approver, and every tool call, sign-in, approval and admin change lands in
an append-only, hash-chained audit log.
> Why let Postgres decide. With one shared credential every user gets the union of
> everyone's access, and a prompt injection in a support ticket can make an assistant that
> holds it read a private table
> (General Analysis, 2025). Guards
> bolted on outside the database get bypassed: a reference read-only Postgres MCP server was
> escaped with COMMIT;
> (Datadog Security Labs, 2025).
| 133 / 133 | 0 | 1.98 ms | 565 req/s |
| attacks blocked, oracle-verified | leaked rows or unapproved writes, 60 LLM episodes | gateway overhead per key lookup, p50 | 20 identities, p95 94.8 ms |
MacBook Air M5, 24 GB, Docker via colima with 4 CPUs / 6 GB · the commands and caveats are under Results
## What changes
| | One shared credential | pgwarden | |
| Who the database sees | one role for every user | the person's own login role, mapped from your IdP | ADR‑0002 |
| What a person can read | the union of everyone's access | their grants, RLS keyed on sessionuser, masking views | ADR‑0005 |
| Read-only | as strong as the wrapper around the SQL | a read-only transaction and one statement per call; no SQL parsing | ADR‑0001 |
| Writes | whatever the role may do | proposed, checked by EXPLAIN, approved by a named person, run once | ADR‑0006 |
| Record | whatever the server logs | append-only, hash-chained, verified independently of the code that wrote it | ADR‑0007 |
## Quickstart
Docker with Compose v2 is all the demo needs.
bash
git clone https://github.com/B0yko/pgwarden && cd pgwarden
docker compose up -d --wait # Postgres, a mock IdP, Mailpit and the gateway
Every port binds to 127.0.0.1. If 5432, 8080, 9400, 1025 or 8025 is taken,
cp .env.example .env, change the ports there, and devtools/check-ports.sh confirms they
are free.
Open : the landing page prints the connect commands for MCP
Inspector, Claude Code and Cursor. With MCP Inspector (needs Node):
bash
npx @modelcontextprotocol/inspector@2.8.0 --server-url http://localhost:8080/mcp --transport http
Connecting walks you through consent, a mock sign-in and a confirmation that names the
Postgres role you will use. Then call whoami, listtables, describetable and query
as any of the demo identities:
| Sign in as | Postgres role | What the database lets you do |
| alice | pwualice | read every region, with PII masked |
| bob | pwubob | read EU rows only, with raw PII; propose writes |
| dana | pwudana | read US rows only, with raw PII; propose writes |
| carol | none | approve writes (the email arrives in Mailpit, ) and open /admin |
| mallory | none | sign in, then be refused: the identity is not mapped to a role |