pgveil
Streams audit events asynchronously to Apache Kafka for compliance logging and downstream security monitoring.
Allows DBeaver to connect to PostgreSQL through pgveil with on-wire PII masking and AST-based SQL firewall enforcement.
Supports Grafana-based observability through OpenTelemetry/Prometheus metrics for monitoring pgveil activity.
Allows LangChain agents to connect through pgveil's PostgreSQL proxy or MCP server to run masked, guarded SQL against live databases.
Allows Metabase to query PostgreSQL through pgveil by pointing it at the proxy port, applying wire-speed PII masking and SQL firewall protections.
Exports observability telemetry through OpenTelemetry so pgveil proxy, masking, and firewall activity can be monitored in OTel-compatible systems.
Provides a PostgreSQL wire-protocol proxy and native MCP server for querying PostgreSQL with dynamic PII masking, a PostgreSQL 17 AST SQL firewall, schema PII discovery, HITL approval holds, row-exfiltration limits, and audit logging.
Exposes Prometheus metrics for monitoring pgveil proxy operations, PII masking, AST firewall decisions, and audit activity.
Works with Supabase-hosted PostgreSQL over TLS, allowing pgveil to proxy and mask Supabase database traffic without requiring PostgreSQL extensions.
This server does not currently have a deployable release on Glama. Follow the repository's setup instructions to install and configure it for your MCP client, including any required credentials and local dependencies.
pgveil
Zero-trust PostgreSQL Wire Protocol v3 proxy & native MCP server in Go — dynamic wire-speed PII masking (8 compliance packs: GDPR, KVKK, PCI-DSS, HIPAA, LGPD, PIPEDA, UK-GDPR, Secrets), real PostgreSQL 17 AST SQL firewall, AST side-channel PII oracle protection, automatic live schema PII discovery, synchronous Human-in-the-Loop (HITL) wire holds, runaway AI-agent loop circuit breaker, shadow audit-only rollout mode, async Kafka audit streaming, OpenTelemetry/Prometheus observability, an embedded Precision Database Workbench (67 KB gzip, Dark + Light theme), and a production Kubernetes Helm chart.
Give AI agents (Claude Code, Cursor, MCP, LangChain), BI tools (Metabase, Superset, DBeaver), and developers live access to PostgreSQL — with zero database extensions, zero schema changes, and a 1-line port swap (5432 → 6432) or zero-Node.js native pgveil mcp.
# Install on macOS (Apple Silicon / Intel) or Linux via Homebrew
brew install duhanguler/tap/pgveil
# Audit any live PostgreSQL database for exposed PII columns in 2 seconds
pgveil discover --dsn "postgres://user:pass@localhost:5432/mydb"- postgres://app:secret@db.internal:5432/prod
+ postgres://app:secret@pgveil.internal:6432/prod?application_name=claude-mcpEmbedded Precision Database Workbench (Dark & Swiss Light)
Built directly into the single Go binary (67 KB gzip) — line-numbered SQL & YAML syntax highlighting, live AST pre-flight indicator, ⌘K Command Palette, right-side Audit Inspector slide-over drawer, live HITL wire-hold countdown, and automatic Dark / Swiss Light theme switching.
Why pgveil?
In 2026, teams are connecting autonomous AI SQL agents, coding assistants (Claude Code, Cursor, MCP servers), and BI analysts directly to PostgreSQL replicas and production databases. One hallucinated DELETE FROM orders WHERE 1=1, a prompt-injected SELECT pg_read_file('/etc/passwd'), a side-channel oracle probe (WHERE tckn LIKE '100000%'), or an innocent SELECT * FROM customers dumping 500,000 customer rows into an LLM context window creates an immediate outage or GDPR / KVKK / PCI-DSS / HIPAA breach.
Capability |
|
|
|
| MCP Wrapper Scripts |
Zero PostgreSQL extensions / RDS, Cloud SQL, Neon, Supabase TLS | Yes | No (superuser ext) | Yes | Yes | Yes |
Works for every client ( | Yes | Yes | Yes | Offline dumps only | MCP only |
Real PostgreSQL 17 AST firewall (CTEs, tautologies, multi-stmt) | Yes | No | No | No | Regex only |
AST PII Side-Channel Oracle Guard ( | Yes | No | No | No | No |
Live wire-speed PII & secret masking ( | Yes ( | Views/static | No | Static dump | Post-fetch only |
Automatic live schema PII discovery & policy generator ( | Yes | No | No | No | No |
Native zero-Node.js MCP stdio server ( | Yes | No | No | No | Node/Python only |
Live synchronous HITL approval hold + Shadow | Yes | No | No | No | No |
Async Kafka audit stream + OTel + Prometheus + Grafana + Helm | Yes | No | Metrics only | No | No |
Related MCP server: psql-mcp
Automatic Live Schema PII Discovery (pgveil discover)
Point pgveil discover at any existing PostgreSQL database to audit unmasked sensitive columns across 8 checksum-validated compliance packs and emit a ready-to-use pgveil.yaml policy block in seconds:
pgveil discover --dsn "postgres://pgveil:pgveil_dev_password@127.0.0.1:5432/pgveil_demo?sslmode=disable"pgveil Schema PII Discovery — database="pgveil_demo" tables=5 columns=38 findings=12
TABLE.COLUMN RISK COMPLIANCE STRATEGY SAMPLE MASKED
------------ ---- ---------- -------- -------------
api_secrets.secret_value CRITICAL SECRETS redact [REDACTED:GITHUB_TOKEN]
customers.full_name MEDIUM GDPR,KVKK hash [heuristic match]
customers.email HIGH GDPR,KVKK partial a***@example.com.tr
customers.phone MEDIUM GDPR,KVKK partial +90 *** ** 21
customers.tckn CRITICAL KVKK partial 100******46
customers.ssn CRITICAL HIPAA redact [REDACTED:US_SSN]
customers.iban HIGH GDPR,KVKK partial TR33 **** **** **** 1326
orders.shipping_note CRITICAL GDPR,KVKK,PCI-DSS partial Call +90 *** ** 21 at gate
payments.card_number CRITICAL PCI-DSS last4 ****-****-****-4242
support_tickets.body CRITICAL GDPR,HIPAA,KVKK,PCI-DSS,SECRETS redact Hello, please refund order ORD-2026-1001 to my IBAN TR33 **** **** **** 1326...
Recommended denied_tables: api_secretsSee It in Action (Real psql & pgx/v5 Wire Sessions)
Connect with any unmodified PostgreSQL client by setting application_name=claude-mcp on port 6432:
-- 1. Structured columns masked dynamically on the wire (JOIN-preserving HMAC hash + partial masks)
SELECT id, full_name, email, phone, tckn, iban FROM customers ORDER BY id LIMIT 4;
id | full_name | email | phone | tckn | iban
----+------------------+---------------------+----------------+-------------+--------------------------
1 | tok_5351939b7cc5 | a***@example.com.tr | +90 *** ** 21 | 100******46 | TR33 **** **** **** 1326
2 | tok_c602dcb1b2f4 | m***@acme.io | +90 *** ** 80 | 123******50 | TR33 **** **** **** 1326
3 | tok_85015ababe75 | e***@eu-shop.de | +49 *** ** 03 | 246******94 | DE89 **** **** **** 3000
4 | tok_e6779f53504a | m***@fintech-us.com | +1 4 *** ** 94 | 314******62 | GB29 **** **** **** 6819
-- 2. Free-text columns auto-scanned for embedded PII & leaked cloud credentials
SELECT id, subject, body FROM support_tickets ORDER BY id LIMIT 2;
id | subject | body
----+------------------------------+-----------------------------------------------------------------------------------------------------------------------------
1 | IBAN refund transfer request | Hello, please refund order ORD-2026-1001 to my IBAN TR33 **** **** **** 1326. My TCKN is 100******46 and email a***@example.com.tr.
2 | API integration error log | Our webhook failed while authenticating with key [REDACTED:AWS_ACCESS_KEY] and card ****-****-****-4242. Contact m***@fintech-us.com (SSN [REDACTED:US_SSN]).
-- 3. Bulk exfiltration capped at 25 rows with genuine PostgreSQL NOTICE
SELECT id, email FROM customers;
NOTICE: pgveil: result truncated to 25 rows (15 excess rows suppressed by profile "ai_agent" row-exfiltration budget)
(25 rows)
-- 4. AST Firewall blocks destructive SQL, tautologies, modifying CTEs, server escapes & PII side-channel oracles
DROP TABLE orders;
-- ERROR: DDL / privilege statement (DROP) is blocked for profile "ai_agent" (SQLSTATE 42501)
DELETE FROM orders WHERE 1 = 1;
-- ERROR: Unscoped DELETE without effective WHERE clause (or tautology like 1=1) is blocked (SQLSTATE 42501)
SELECT id, full_name FROM customers WHERE tckn LIKE '100000%';
-- ERROR: PII side-channel inference blocked: protected column "tckn" referenced in WHERE predicate (SQLSTATE 42501)
SELECT id, SUBSTRING(iban, 1, 10) AS prefix FROM customers;
-- ERROR: PII side-channel inference blocked: protected column "iban" referenced in expression function substring() (SQLSTATE 42501)
SELECT pg_read_file('/etc/passwd');
-- ERROR: Dangerous PostgreSQL function blocked: pg_read_file (SQLSTATE 42501)
-- 5. Live Synchronous HITL Hold: connection pauses cleanly until an operator clicks Approve in the Web Console
UPDATE orders SET status = 'refunded' WHERE id = 1001;
-- [Paused on wire -> Operator approves in http://localhost:8088 -> Immediately resumes]
UPDATE 1Architecture
flowchart LR
Clients["Clients & AI Agents<br/>psql · pgx · psycopg · DBeaver<br/>Claude/Cursor MCP · LangChain"] -->|"PostgreSQL Wire Protocol v3<br/>(:6432 TCP / TLS)<br/>or Native MCP stdio"| Proxy["pgveil Proxy & MCP (Go)<br/>• Simple + Extended Query (Cached Stmts)<br/>• PostgreSQL 17 AST + PII Oracle Guard<br/>• Rate Limiter & Runaway Loop Breaker<br/>• Synchronous HITL Hold + Shadow Mode<br/>• Dynamic Wire-Speed PII Masker (8 Packs)<br/>• Embedded Web Console + Discovery (:8088)"]
Proxy -->|"Policy-Verified SQL<br/>(Optional Upstream TLS)"| PG[("PostgreSQL 14–17<br/>RDS · Cloud SQL · Neon · Local")]
Proxy -->|"Non-Blocking Async Events"| Kafka["Apache Kafka / Redpanda<br/>• pgveil.audit.queries<br/>• pgveil.alerts.security"]
Kafka --> Worker["pgveil-audit-worker (Go)<br/>• Batch pgx Sink (pgveil_audit_log)<br/>• Dead-Letter Queue (DLQ)<br/>• Burst Attack Anomaly Webhook"]
Proxy -.->|"OTLP / Metrics"| Obs["OpenTelemetry + Jaeger<br/>Prometheus + Grafana"]
Worker -.->|"Metrics"| ObsCore Engineering Highlights
Full Wire Protocol v3 + Extended Binary Fidelity (
internal/pgwire,internal/proxy): SupportsSSLRequest(client TLS termination & upstream TLS for RDS/Cloud SQL/Neon/Supabase),GSSENCRequest,CancelRequest,SCRAM-SHA-256/MD5/cleartext/trustauth relay, Simple Query ('Q'), and Extended Query pipelines (Parse,Bind,Describe,Execute,Sync) with per-session prepared statement metadata caching so strict binary drivers (pgx/v5,psycopg3,JDBC) work seamlessly (ADR-003).PostgreSQL 17 AST Firewall + Side-Channel Oracle Guard (
internal/firewall): Embeds PostgreSQL's own C parser (libpg_query) to defeat bypasses that regex proxies miss — modifying CTEs (WITH d AS (DELETE ...) SELECT * FROM d), always-true tautologies (WHERE 1=1,WHERE id=5 OR true), multi-statement SQLi,pg_read_file/COPY TO PROGRAM/DO $$/SET ROLE, plus AST side-channel PII inference probes (WHERE tckn LIKE '100%',SUBSTRING(iban,1,8) AS x,tckn || '',ORDER BY ssn,CASE WHEN ssn = ...) (ADR-002, ADR-005).Zero-False-Positive 8-Pack Global Compliance Engine (
internal/pii):kvkk(Türkiye): 11-digit TCKN mod-10, 26-char TR IBAN ISO 13616 Mod-97, 10-digit VKN tax ID checksum, Turkish mobile phones, emailgdpr(EU): EU IBAN Mod-97 (DE,FR,GB,NL,ES,IT, ...), email, international phones, IPv4pci-dss: Credit Cards (Visa, Mastercard, Amex, Discover, Troy) with Luhn + BIN validationhipaa(US): US SSN (SSA area/group/serial validation), email, phonelgpd(Brazil): Brazilian CPF (dual mod-11 check digits)pipeda(Canada): Canadian SIN (Luhn validation)uk-gdpr(UK): UK NINO (official HMRC prefix exclusion rules)secrets: AWS access keys (AKIA...), GitHub tokens (ghp_,github_pat_), OpenAI keys (sk-...), JWTs, PEM private keys6 Masking Strategies:
partial,redact,last4,hash(HMAC-SHA256 deterministic JOIN-preserving pseudonymization),fake, andnull.
Enterprise Rollout Safety: Per-profile Shadow / Audit-Only Mode (
mode: audit) emitsWOULD_BLOCK/WOULD_HITLtelemetry without breaking traffic; Runaway AI-Agent Loop Circuit Breaker & QPM Rate Limiter (internal/ratelimit) stops stuck retry loops withSQLSTATE 53300; Webhook alerts notify Slack/Teams/Discord on live HITL holds and CRITICAL blocks; SIGHUP / REST API hot-reload swaps policies with zero downtime.
Benchmarks (Real Measured Results)
All benchmarks below were executed locally on Apple M3 Pro (arm64) against PostgreSQL 16.14 using our reproducible scripts in benchmarks/.
1. Live pgbench Wire-Protocol Throughput & Overhead
8 concurrent clients, 4 threads, returning 5 rows × 7 columns (id, full_name, email, phone, tckn, iban, city) — 25 PII cells masked per query in ai_agent mode:
Mode | Throughput (TPS) | Avg Latency | Added Wire Overhead | Failed Tx |
Direct PostgreSQL 16 ( | 107,536 TPS |
| baseline |
|
Through | 29,161 TPS |
|
|
|
Through | 25,012 TPS |
|
|
|
625,000+ dynamically masked PII cells per second on a single node with sub-millisecond (
0.246 ms) overhead and 0 failed transactions across 150,098 queries.
2. Go Core Microbenchmarks (go test -bench=. -benchmem)
Benchmark | Latency / Op | Memory / Op | Allocs / Op |
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
3. k6 Control Plane & End-to-End Wire Load Test (benchmarks/k6/control_plane_load.js)
30 concurrent VUs, 25 seconds, mixing AST+PII inspections and live PostgreSQL wire proxy executions:
Metric | Measured Result |
Total Requests / Checks Passed | 25,699 requests · 57,832 / 57,832 checks ( |
Error Rate ( |
|
| p50 |
| p50 |
Quick Start
Option 1 — Homebrew (macOS Apple Silicon, Intel & Linux)
brew install duhanguler/tap/pgveil
# 1. Scan any existing PostgreSQL database for exposed PII columns & generate policy YAML
pgveil discover --dsn "postgres://user:pass@localhost:5432/mydb"
# 2. Start the wire proxy (:6432) + embedded Workbench UI (:8088)
pgveil serve --config configs/pgveil.yaml
# 3. Or run the zero-Node.js native MCP stdio server for Claude Desktop / Cursor
pgveil mcp --config configs/pgveil.yaml --profile ai_agentOption 2 — Full Enterprise Stack in 1 Command (Docker Compose)
Launches PostgreSQL 16 (pre-seeded with synthetic e-commerce/fintech PII), pgveil Proxy (:6432 wire + :8088 Web Console), Redpanda (Kafka), pgveil-audit-worker, Jaeger, Prometheus, and Grafana (pre-provisioned dashboard):
git clone https://github.com/duhanguler/pgveil.git
cd pgveil
docker compose up --buildEmbedded Precision Workbench & PII Discovery:
http://localhost:8088PostgreSQL Wire Proxy:
postgres://pgveil:pgveil_dev_password@localhost:6432/pgveil_demo?application_name=claude-mcpGrafana Dashboard:
http://localhost:3000(admin/pgveil_grafana)Jaeger Distributed Traces:
http://localhost:16686
Option 3 — Build From Source & CLI (serve, discover, mcp, scan, validate)
make build
# Start wire proxy + embedded Web Console
./bin/pgveil serve --config configs/pgveil.yaml
# Auto-discover unmasked PII columns & generate a pgveil.yaml policy block
./bin/pgveil discover --dsn "postgres://user:pass@localhost:5432/mydb" --format yaml
# Run zero-Node.js native MCP stdio server (hides denied_tables, enforces AST + PII masking)
./bin/pgveil mcp --config configs/pgveil.yaml --profile ai_agent
# Test any SQL query against the AST firewall in CI (exits 2 if BLOCKED)
./bin/pgveil scan --sql "SELECT id FROM customers WHERE tckn LIKE '100000%'" --profile ai_agentOption 4 — Connect Claude Desktop / Cursor MCP (Zero Node.js or Wire Mode)
Native single-binary MCP (examples/mcp-claude/pgveil_native_mcp.json):
{
"mcpServers": {
"pgveil-native-postgres": {
"command": "/opt/homebrew/bin/pgveil",
"args": ["mcp", "--config", "/path/to/configs/pgveil.yaml", "--profile", "ai_agent"]
}
}
}Or wire-proxy mode with the official Postgres MCP server (examples/mcp-claude/claude_desktop_config.json) and Python psycopg agent (examples/python-agent/agent_demo.py).
Option 5 — Production Kubernetes Deployment (Helm)
helm lint deploy/helm/pgveil
helm upgrade --install pgveil deploy/helm/pgveil \
--namespace database-security --create-namespace \
--set upstream.addr=postgres-primary.database.svc.cluster.local:5432 \
--set security.maskingSecret="$PGVEIL_MASKING_SECRET"Architecture Decision Records (ADRs)
ADR-001: PostgreSQL Wire Protocol v3 Proxy vs. DB Extensions or ORM Middleware
ADR-002: Real PostgreSQL 17 AST Parsing vs. Regex SQL Filtering
ADR-003: Wire-Level Dynamic Masking & Extended Query Protocol Binary Fidelity
ADR-004: Non-Blocking Kafka Audit Pipeline & Synchronous HITL Wire Holds
ADR-005: AST Side-Channel PII Inference Protection & Native MCP Server Mode
Project Layout
pgveil/
├── cmd/
│ ├── pgveil/ # Single-binary CLI (serve, discover, mcp, scan, validate) + embedded UI
│ └── audit-worker/ # Kafka consumer group worker (batch pgx sink, DLQ, burst anomaly alerts)
├── internal/
│ ├── pgwire/ # PostgreSQL Wire Protocol v3 binary framing (Simple & Extended)
│ ├── firewall/ # PostgreSQL 17 C AST SQL firewall + PII side-channel oracle guard
│ ├── pii/ # Zero-false-positive 8-pack compliance engine (GDPR/KVKK/PCI/HIPAA/LGPD/PIPEDA/UK/Secrets)
│ ├── discover/ # Live information_schema PII scanner & YAML policy synthesizer
│ ├── mcpserver/ # Native zero-dependency JSON-RPC 2.0 MCP stdio server
│ ├── ratelimit/ # Per-profile QPM limiter & runaway AI-agent loop circuit breaker
│ ├── proxy/ # Bidirectional wire proxy, upstream TLS, shadow audit mode & live HITL holds
│ ├── hitl/ # Synchronous approval coordinator with SSE live notifications
│ ├── policy/ # Declarative YAML RBAC profiles + SIGHUP/API hot-reload
│ ├── events/ # Non-blocking audit ring buffer, SSE hub & franz-go Kafka producer
│ ├── telemetry/ # OpenTelemetry OTLP tracing + Prometheus histograms/counters
│ ├── api/ # Control Plane REST/SSE API, live wire Playground & Discovery endpoint
│ └── webui/ # //go:embed compiled React + TypeScript Control Plane
├── web/ # React 18 + TypeScript + Vite + Tailwind Console source
├── configs/pgveil.yaml # Declarative profiles (ai_agent, analyst, developer, admin)
├── deploy/
│ ├── docker/ # Postgres demo seed, Prometheus config & Grafana dashboard JSON
│ └── helm/pgveil/ # Production Kubernetes Helm chart (HPA, PDB, NetworkPolicy)
├── benchmarks/ # Reproducible pgbench comparison & k6 load test suite
├── examples/ # Native MCP, Claude/Cursor MCP & Python psycopg AI agent integrations
└── docs/adr/ # Architecture Decision RecordsContributing & License
Contributions, regional compliance packs, and AST security test cases are very welcome! See CONTRIBUTING.md and SECURITY.md.
Licensed under the Apache License 2.0 — see LICENSE.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
This server cannot be deployed
Maintenance
Related MCP Connectors
Guard AI agents' PostgreSQL/MySQL access via MCP: SQL audit, auth, masking, write approval
Safe, read-only Postgres and MySQL access for AI agents. Audit log + column-level controls.
Deterministic safety, correctness & cost gate that vets Postgres SQL before your AI agent runs it.
Governed SQL access to your databases: redaction, query review and an audit log.
Related MCP Servers
- FlicenseNot gradedqualityDmaintenanceAn MCP server that gives an AI agent scoped, safe access to your Postgres databases with per-connection access control, row caps, timeouts, and defense-in-depth read-only enforcement.-
- AlicenseNot gradedqualityCmaintenanceA hardened, read-only Postgres MCP server that enables LLMs to safely query databases without write, DDL, shell, or credential exposure.MIT
- AlicenseAqualityDmaintenanceAn MCP server that enables AI agents to securely interact with PostgreSQL databases with least-privilege scopes, PII masking, and human approval for writes.4MIT
- AlicenseAqualityBmaintenanceA security-hardened Postgres MCP server that enables LLM agents to run safe, read-only SQL queries with enforcement via SQL-AST inspection and read-only transactions.1MIT