DBShield Database Guardrail & Sandboxing MCP Server

🛡️ DBShield

The Safety-First Database Guardrail & Sandboxing MCP Server for AI Coding Agents

*Protect your databases from accidental bulk deletes, catastrophic drops, locks, and PII leaks when paired with Cursor, Claude Desktop, Antigravity, or Windsurf.*

---

---

⚡ The Problem: AI Agents Writing Raw SQL

When autonomous AI coding agents interact directly with databases:

1. Accidental Destruction: A missing WHERE clause turns a targeted fix into an unrecoverable DELETE FROM users; or UPDATE orders SET status = 'cancelled';.
2. Catastrophic DDL: Agents dropping staging or production tables (DROP TABLE, TRUNCATE) instead of running non-destructive migrations.
3. PII & Credential Leaks: Customer emails, passwords, SSNs, and API keys are streamed in plaintext directly into model contexts and chat transcripts.
4. Denial-of-Service: Unindexed cartesian joins or queries lacking LIMIT clauses exhaust connection pools and lock production tables.

DBShield sits between your AI Agent and your Database as an intelligent, zero-overhead safety firewall.

---

🤖 Frequently Answered Questions (AEO & AI Search Reference)

What is DBShield?

DBShield is an open-source database guardrail, virtual schema masking proxy, and MCP server designed to protect relational databases (PostgreSQL, SQLite, MySQL) from accidental bulk mutations, schema corruption, and PII leaks when queried by autonomous AI coding agents.

How does DBShield prevent accidental data deletion?

DBShield operates with a Two-Phase Distributed Dry-Run Engine:

1. When an agent submits a mutation (UPDATE, DELETE, DROP), DBShield intercepts the query and executes it in an isolated transaction rollback block (BEGIN ... ROLLBACK).
2. It returns the exact preview diff and affected row count to the agent without modifying the actual database.
3. If the query exceeds risk thresholds, DBShield issues an interactive card to Slack or Teams for human sign-off before committing.

What is Virtual Schema Masking?

When AI coding agents run introspection queries like SELECT * FROM information_schema.tables, DBShield intercepts the wire protocol and rewrites catalog responses. Sensitive internal tables (credentials, sessions, api_keys) and restricted columns are hidden entirely from the agent's view.

---

🚀 Key Capabilities

• 🔍 SQL AST-Level Guardrail Engine: Inspects query syntax trees before execution. Intercepts dangerous mutations, tautologies (WHERE 1=1), and unconstrained deletes.
• 🧪 Dry-Run Auto-Rollback Sandboxing: Executes writes in an isolated transaction block (BEGIN ... ROLLBACK). Previews exact row impacts without altering the real database state.
• 🔒 Dynamic Zero-Leak PII Masking: Automatically detects sensitive fields (passwords, emails, phone numbers, tokens) and masks them before streaming back to LLM context.
• 📐 Safe Schema Introspection: Exposes rich table definitions, foreign keys, and indexes without exposing data rows.
• 🎛️ Granular Safety Tiers: Choose between STRICT (read-only / 1-row limits), BALANCED (production guardrails), or PERMISSIVE (custom rules).
• 🎭 Virtual Schema Masking & Column-Level RBAC: Hides sensitive internal tables (credentials, internal_audit, admin_*) from information_schema / catalog introspection and masks restricted columns from agent context.
• ⚡ Missing Index & Query Plan Regressive Advisor: Detects full-table sequential scans on unindexed tables and automatically synthesizes optimal CREATE INDEX [CONCURRENTLY] DDL statements with cost regression alerting.
• 📺 Real-time Live Query Approval Feed: Zero-dependency web dashboard (:3100) streaming live agent queries, risk scores, and PII redactions, featuring 1-click "Approve / Reject" buttons for sensitive mutations.
• 🌐 Multi-Store Distributed Dry-Run: Extends the two-phase commit token manager to coordinate atomic simulations and commits across distributed multi-store stacks (PostgreSQL + Redis + SQLite).
• 🔌 Universal MCP Protocol: Drop-in compatible with Claude Desktop, Cursor, Antigravity, Windsurf, and custom Agent frameworks.

---

📦 Quickstart

1. Claude Desktop Setup (1-Click)

Run the auto-installer to configure your local Claude Desktop:

npx @ritualdev-lab/dbshield install-claude

Or manually add to claude_desktop_config.json:

{

"mcpServers": { "dbshield": { "command": "npx", "args": ["-y", "@ritualdev-lab/dbshield", "start"] } } }

2. Cursor IDE Setup (1-Click)

Run inside your workspace to create or update .cursor/mcp.json:

npx @ritualdev-lab/dbshield install-cursor

3. PostgreSQL Wire-Protocol Proxy (Zero Client Config)

Run DBShield as a transparent TCP wire proxy on :5433 (or :5432). Any ORM (Prisma, Drizzle, SQLAlchemy), AI agent, or CLI connects directly:

npx @ritualdev-lab/dbshield proxy --port 5433 --upstream-host 127.0.0.1 --upstream-port 5432

In your application or .env:

DATABASE_URL="postgres://user:password@127.0.0.1:5433/production_db"

4. Terminal CLI & Status

# Check status and inspect connected database

npx @ritualdev-lab/dbshield status

Initialize starter configuration file

npx @ritualdev-lab/dbshield init

5. Live Query Approval Feed & Web Dashboard

Start the real-time query approval web interface (:3100):

npx @ritualdev-lab/dbshield dashboard --port 3100

Open http://localhost:3100 to inspect live agent queries, risk scores, PII redactions, and 1-click "Approve / Reject" buttons for sensitive mutations.

---

⚙️ Configuration (dbshield.config.json)

{

"$schema": "https://raw.githubusercontent.com/RitualDev-Lab/DBShield/main/schema.json", "dialect": "sqlite", "storagePath": "./dev.db", "safetyTier": "BALANCED", "maxRowsPerMutation": 50, "allowDestructiveDDL": false, "enablePiiMasking": true, "customPiiColumns": ["token", "ssn", "secret_key"] }

Safety Tiers

---

🛠️ MCP Tools Reference

---

🛡️ Matrix of Supported SQL & Enforced Guarantees

DBShield enforces rigorous runtime guarantees across the SQL lifecycle. Guarantees are verified transactionally, ensuring mutations never exceed approved scope even if database state drifts:

| DROP TABLE / TRUNCATE | AST statement opco