⚡ The Architecture: Grounding → Generation → Verification
AI coding assistants (Cursor, Claude Code, Windsurf, Codex) are fluent in SQL syntax, but fail at production relational databases because raw schema DDL omits implicit operational invariants:
SCHEMAP 4.0
┌─────────────────┐
│ Database Schema │
└────────┬────────┘
│ (Introspect tables, FKs, types)
▼
┌─────────────────────┐
│ Semantic Compiler │
│ │
│ • Entity Roles │
│ • Measure Units │
│ • Join Graphs │
│ • Tenant Invariants │
│ • Lifecycle Rules │
│ • Provenance Tags │
└─────────┬───────────┘
│
▼
GroundedPlan
│ (Provided to LLM via MCP or CLI)
▼
┌─────────────────────┐
│ AI Coding Agent │
│ (Claude, Cursor, │
│ Gemini, Codex) │
└─────────┬───────────┘
│
▼
Generated SQL
│
▼
┌─────────────────────┐
│ AST Policy Engine │
│ │
│ • Mutation blocking │
│ • Tenant validation │
│ • Soft-delete check │
│ • Cartesian hazard │
└─────────┬───────────┘
│
ALLOW / REJECT / RE-VALIDATE
│
▼
Database Execution
🛑 The Problem: The Hidden Traps of Naked Schema Prompts
In production databases, queries fail not from syntax errors, but from missing invariants:
- The "Cents Illusion": Models sum integer currency columns (
amount_cents), reporting $19,900.00 instead of $199.00 ($100\times$ metric distortion).
- Zombie Records: Soft-deleted records and cancelled subscriptions (
deleted_at IS NOT NULL or is_deleted = TRUE) are counted as active data.
- Tenant Data Leaks: Multi-table joins drop tenant predicates (
org_id), leaking neighboring customer records.
- Cartesian Hazards: Disconnected joins (
FROM invoices, plans) produce accidental Cartesian products.
- Destructive Operations: Agents generate
DELETE or DROP TABLE queries without execution safeguards.
🚀 Quick Start: Model Context Protocol (MCP)
Schemap exposes three native MCP tools for Cursor, Claude Code, and Windsurf.
1. Configure MCP Server
Add Schemap to your claude_desktop_config.json or .cursor/mcp.json:
{
"mcpServers": {
"schemap": {
"command": "uvx",
"args": ["schemap-tool", "mcp"],
"env": {
"DATABASE_URL": "postgresql://user:password@localhost:5432/production_db"
}
}
}
}
Zero YAML required. Schemap inspects the database connection locally and provides three tools:
| Tool | Phase | Function |
|---|
schemap_ground | Before writing SQL | Resolves target tables, foreign-key join paths, monetary measures, and tenant invariants with explicit provenance ([DECLARED] vs [INFERRED]). |
schemap_verify | Before executing SQL | Deny-by-default AST policy circuit breaker that blocks mutations (DELETE, DROP, UPDATE), Cartesian products, and tenant omissions. |
schemap_patch | Remediating SQL | Injects missing tenant and soft-delete filters, then re-validates the patched AST to ensure no hazards remain. |
💻 CLI Usage
For terminal workflows, scripts, and local pair-programming:
# 1. Ground an analytical question before writing SQL
schemap ground "What was Org 42's revenue last month?" --db "$DATABASE_URL" --tenant-id 42
# 2. Verify SQL before executing against production
schemap verify "SELECT * FROM orders" --db "$DATABASE_URL" --tenant-id 42
# 3. Patch missing invariants with safety re-verification
schemap patch "SELECT * FROM orders" --db "$DATABASE_URL" --tenant-id 42
🔬 Evidence & Evaluation
Schemap maintains three canonical evaluation documents separating live model reasoning, controlled policy verification, and domain generalization:
1. Master Methodology & Headline Results — EVALUATION.md
- Analytical Success: In our 500-task controlled benchmark on seeded operational schemas, the raw-schema baseline achieved 10.6% first-pass analytical success versus 90.0% with Schemap grounding.
- Destructive Operation Blocking: Schemap blocked 100% of unsafe operations tested in our mutation suite (0 escapes).
- Decoupled Denominators: Analytical correctness and mutation safety are independently measured.
- Evaluates live completions from Gemini 3.8 Flash executing against a seeded SQLite operational database.
- Exact Dataset Match: Lifted from 2/8 (25%) on raw DDL to 8/8 (100%) with Schemap grounding.
- Safety Gate: Unguarded models produced 2 destructive mutations;
schemap_verify blocked 2/2.
- Evaluates heuristic convention discovery across 6 non-SaaS domains (E-Commerce, Fintech Ledger, Healthcare EHR, Education LMS, HR & Payroll, IoT Fleet).
- Implements a three-tier provenance model:
DECLARED: Explicit constraints defined in DDL or configuration.INFERRED: Recovered via structural conventions (e.g. _cents, _id, timestamps).UNKNOWN: Flagged ambiguities (e.g., dual foreign keys between the same tables) requiring human declaration.
🗄️ Supporting Tools & Capabilities
Beyond real-time MCP grounding, Schemap includes tools for local repo maintenance:
- Static Agent Context:
schemap context compiles a token-compressed schemap_database_context.md.
- Agent Rule Files:
schemap agents generates synchronized CLAUDE.md, AGENTS.md, and .cursorrules.
- Schema Health Diagnostic:
schemap doctor audits missing foreign keys, orphan tables, and naming consistency.
- Supported Databases: PostgreSQL, MySQL, SQLite, Turso / libSQL, Oracle.
📄 License & Community
Schemap is licensed under the MIT License.
