MCP Database Doctor

MCP Database Doctor

Catch dangerous PostgreSQL migrations and slow queries before your AI agent ships them — offline, no DB credentials.

Offline PostgreSQL migration linting and query analysis for AI coding agents. Detects table-locking DDL, dangerous type changes, slow query patterns, and execution plan issues before they reach production. Nothing leaves your machine, no database connection required.

---

Quick Install

Cursor

Click the button above to install in one step, or use this link:
cursor://anysphere.cursor-deeplink/mcp/install?name=database-doctor&config=eyJjb21tYW5kIjoibnB4IiwiYXJncyI6WyIteSIsIm1jcC1kYXRhYmFzZS1kb2N0b3IiXX0=

Or add manually to ~/.cursor/mcp.json:

{
  "mcpServers": {
    "database-doctor": {
      "command": "npx",
      "args": ["-y", "mcp-database-doctor"]
    }
  }
}

Claude Code

claude mcp add database-doctor -- npx -y mcp-database-doctor

Or, if available in the Cursor plugin marketplace:

/plugin marketplace add petrovicistefan/mcp-marketplace

Claude Desktop

Add to claude_desktop_config.json:

{
  "mcpServers": {
    "database-doctor": {
      "command": "npx",
      "args": ["-y", "mcp-database-doctor"]
    }
  }
}

VS Code

Or add to .vscode/mcp.json:

{
  "mcpServers": {
    "database-doctor": {
      "command": "npx",
      "args": ["-y", "mcp-database-doctor"]
    }
  }
}

Any MCP Client

npx -y mcp-database-doctor

⭐ Star this repository to support the project and stay updated! → Give a star

---

📋 Table of Contents

• Why Database Doctor?
• Use Cases
• What It Checks
• How It Compares
• Tools
• Example Prompts
• Limitations
• Development
• More MCP Servers by the Author
• Contributing
• License

---

Why Database Doctor?

The hook: Your AI agent generates migrations that look harmless: CREATE INDEX, ALTER COLUMN ... TYPE, ADD COLUMN NOT NULL. But each one can lock your production table for minutes or hours, block every write, and take down your app.

Database Doctor catches these before they ship:

• No database required: Static analysis only, works with uncommitted code
• No credentials: Nothing connects to your database or executes SQL
• No network: Everything runs locally on your machine
• AI-native: Designed for AI coding agents (Claude Code, Cursor, GitHub Copilot)

When to Use

✅ Before shipping migrations — Catch CREATE INDEX without CONCURRENTLY, dangerous type changes, volatile defaults
✅ Reviewing slow queries — Detect SELECT *, deep OFFSET, unbounded writes, unindexed predicates
✅ Analyzing EXPLAIN plans — Spot large sequential scans, row estimate errors, sort spills, high loop counts
✅ Suggesting indexes — Get conservative DDL candidates for WHERE clause columns

---

Use Cases

1. AI Agent Code Review

Your agent writes the migration. Database Doctor reviews it before committing.

User: "Add an email column to the users table"

Agent writes:
  ALTER TABLE users ADD COLUMN email VARCHAR(255) NOT NULL;

Database Doctor flags:
  ⚠️  NOT_NULL_CHANGE (medium severity)
  Adding NOT NULL requires a full table scan and may hold locks.
  Recommendation: Backfill data first, then add NOT NULL separately.

Agent rewrites:
  ALTER TABLE users ADD COLUMN email VARCHAR(255);
  -- Backfill in application code or batched UPDATE
  ALTER TABLE users ALTER COLUMN email SET NOT NULL;

2. Pre-Commit Checks

Catch dangerous migrations before they reach CI.

Ask your AI: "Check all migrations in db/migrations/ for safety"

Database Doctor reviews each file and reports:

• Destructive DDL (DROP, TRUNCATE)
• Blocking index creation
• Table-rewriting column changes
• Constraint validation without NOT VALID
• Transactions that can't hold CONCURRENTLY operations

3. Query Optimization

Find performance issues before they hit production.

Your agent generates:

SELECT * FROM orders 
WHERE LOWER(email) = 'user@example.com' 
OFFSET 10000 
LIMIT 20;

Database Doctor flags:

• SELECT_STAR: Wildcard projection couples schema to caller
• FUNCTION_PREDICATE: LOWER() may not use an index on email
• DEEP_OFFSET: Offset 10000 discards many rows, use keyset pagination

4. EXPLAIN Plan Review

Submit a slow query's execution plan for analysis.

# On your test database
EXPLAIN (FORMAT JSON) SELECT ... > plan.json

# In your AI client
"Review this execution plan from plan.json"

Database Doctor detects:

• Sequential scans on large tables
• Row estimate errors (10x+ off)
• Sort operations spilling to disk
• High loop counts in nested joins

---

What It Checks

Migration Safety (check_migration)

Query Analysis (analyze_query)

EXPLAIN Plan Analysis (explain_plan)

---

How It Compares

As of October 2026. All comparisons stated cautiously based on public documentation.

Our differentiators:

• Broadest scope: migrations + queries + EXPLAIN plans + index suggestions (4 capabilities in one tool)
• Zero setup: No database, no credentials, no config — works on uncommitted code
• Privacy-first: Completely offline, nothing sent anywhere
• PostgreSQL-native: Not regex-based, handles comments, strings, dollar quotes, nested blocks
• Lightweight: Zero dependencies beyond MCP SDK and Zod

When to use alternatives:

• MigrationPilot: Need 112 rules, auto-fix, VS Code extension, GitHub Action with SARIF
• Locksmith: Need paste-ready safe rewrites and lock matrix documentation
• Ballast: Need load-aware analysis weighted by real table size (requires DB connection)
• DBHub: Need to connect to live databases for exploration and guarded SQL execution

---

Tools

Database Doctor exposes 5 MCP tools for AI agents:

migrations (optional array)
plans (optional array) | Aggregate review of supplied artifacts (not live database health) |

All tools are read-only, idempotent, and require no authentication.

Reports include:

• code: Stable identifier for the finding type
• severity: high, medium, or low
• message: What the issue is
• recommendation: How to fix it
• statement: Which statement in multi-statement SQL (1-indexed)

---

Example Prompts

For migrations:

"Check this migration for locking issues"
"Review db/migrations/003_add_email_index.sql before I commit"
"Is this ALTER TABLE safe for a production table with 10M rows?"

For queries:

"Analyze this query for performance issues"
"Why is this SELECT slow?"
"Review the queries in src/repositories/user.ts"

For EXPLAIN plans:

"Review this EXPLAIN plan from plan.json"
"What's wrong with this execution plan?"

For index suggestions:

"What indexes would help this query?"
"Suggest indexes for this WHERE clause"

For aggregate review:

"Review all migrations in db/migrations/ for safety"
"Check queries.sql and migrations.sql for issues"

Integration with development workflow:

"Before I commit, check the migration I just generated"
"Add this to pre-commit: check all .sql files for dangerous patterns"

---

Limitations

Database Doctor uses heuristic static analysis, not a full PostgreSQL parser or proof of safety.

What it handles well

✅ Comments (single-line -- and nested block /* */)
✅ String literals (including escaped E'...')
✅ Dollar-quoted strings ($$, $tag$)
✅ Quoted identifiers ("column_name")
✅ Common DDL and DML patterns

Known limitations

⚠️ Not a full SQL parser: Complex CTEs, nested scopes, unusual DDL may produce false positives or missed findings
⚠️ No schema metadata: Can't verify if a column exists, what type it is, or what indexes are present
⚠️ Index inference is conservative: Supports one unquoted table, no joins/subqueries, no composite index optimization
⚠️ Stored procedure bodies not analyzed: SQL inside functions, DO blocks, dynamic strings is not inspected
⚠️ No execution: Can't measure actual query time, lock duration, or real plan costs
⚠️ PostgreSQL-first: Not tested on MySQL, SQL Server, Oracle, or other dialects

What findings mean

✅ Finding detected: Review the specific pattern before applying
⚠️ No findings: Does NOT mean the SQL is safe, performant, or valid PostgreSQL
⚠️ Absence of a finding is not authorization to run a migration in production

Always test migrations on a safe environment before production.

---

Development

Requirements: Node.js >=22.18 (Node 24 recommended)

# Install dependencies
npm install

# Type check
npm run check

# Run tests (core logic, no network)
npm test

# Build
npm run build

# Integration tests (MCP stdio after build)
npm run test:integration

# Verify package contents
npm pack --dry-run

Test coverage: 53 core tests covering:

• SQL masking (comments, strings, dollar quotes, quoted identifiers)
• Query analysis (all 8 rules)
• Migration checks (all 9 rules)
• EXPLAIN plan parsing and analysis
• Index suggestion logic
• Health report aggregation

CI: GitHub Actions runs type check, tests, build, integration tests, and package verification on every push and PR.

---

More MCP Servers by the Author

Part of the petrovicistefan MCP suite — local-first guardrails for AI coding agents.

All tools in this family are:

• ✅ Local-first: Everything runs on your machine
• ✅ Read-only: No destructive operations (except explicit opt-in)
• ✅ No API keys: No accounts, no telemetry, no network calls (unless opted in)
• ✅ AI-native: Built specifically for AI coding agents

---

Commercial Roadmap

Free forever:

• Local query, migration, and EXPLAIN plan analysis
• All 5 MCP tools
• No usage limits
• No telemetry

Pro tier (planned, opt-in):

• History tracking (before/after comparisons)
• CI policies and advanced recommendations
• Hosted HTTP API (for non-MCP integrations)
• Quotas via control-plane for hosted path only

Team tier (planned, opt-in):

• Shared migration policies
• Centralized reports
• Fleet-wide query analysis

Local tools stay free and offline forever. Paid features are additive and require explicit opt-in.

---

Contributing

Contributions are welcome! Please read CONTRIBUTING.md first.

Good first contributions:

• Add test cases for false positives or missed findings
• Improve documentation and examples
• Add support for more PostgreSQL versions
• Extend query or migration rules

Not currently accepting:

• Support for other databases (MySQL, SQL Server, etc.) without a clear use case
• Network-based features (stay local-first)

Contribution guide · Open issues · Report a false positive

---

License

MIT © Stefan Petrovici

See LICENSE for details.

---

About the Author

I'm Stefan Petrovici: passionate about IT, a husband and a father. I built Database Doctor and the entire MCP suite on my own. I'm looking for a job.

I build web applications end to end—frontend, backend, APIs and deployment—and I'm happy to work on anything else that needs building. This repository shows how I work: tests, CI, careful documentation and attention to detail.

I also build WordPress and WooCommerce plugins, available at pluginsforstores.com.

If your team is hiring, write to me at hello@petrovicistefan.ro.

---

⭐ Support This Project

Found this useful? Star this repository!

A GitHub star helps other developers discover the project and lets you save it for later. Thanks for supporting open source!

---

Database Doctor is not affiliated with PostgreSQL, Anthropic, or any other vendor mentioned in this document.