MCP Database Doctor

MCP Database Doctor

在 AI Agent 发布迁移之前，捕获危险的 PostgreSQL 迁移和慢查询——离线运行，无需数据库凭据。

面向 AI 编码 Agent 的离线 PostgreSQL 迁移检查与查询分析工具。在问题进入生产环境之前，检测会锁定表的 DDL、危险的类型变更、慢查询模式和执行计划问题。所有数据都留在本机，无需连接数据库。

---

快速安装

Cursor

点击上方按钮即可一步完成安装，也可以使用此链接：
cursor://anysphere.cursor-deeplink/mcp/install?name=database-doctor&config=eyJjb21tYW5kIjoibnB4IiwiYXJncyI6WyIteSIsIm1jcC1kYXRhYmFzZS1kb2N0b3IiXX0=

也可以手动添加到 ~/.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

或者，如果 Cursor 插件市场中有此插件：

/plugin marketplace add petrovicistefan/mcp-marketplace

Claude Desktop

添加到 claude_desktop_config.json：

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

VS Code

也可以添加到 .vscode/mcp.json：

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

任意 MCP 客户端

npx -y mcp-database-doctor

⭐ 为此项目点亮 Star，支持项目并获取最新动态！ → 点亮 Star

---

📋 目录

• 为什么选择 Database Doctor？
• 使用场景
• 检查内容
• 对比
• 工具
• 提示词示例
• 限制
• 开发
• 作者的更多 MCP 服务
• 贡献
• 许可证

---

为什么选择 Database Doctor？

关键问题： AI Agent 生成的迁移看起来可能无害：CREATE INDEX、ALTER COLUMN ... TYPE、ADD COLUMN NOT NULL。但这些操作都可能让生产表锁定数分钟甚至数小时，阻止所有写入，导致应用宕机。

Database Doctor 会在发布之前捕获这些问题：

• 无需数据库：仅进行静态分析，可检查尚未提交的代码
• 无需凭据：不会连接数据库，也不会执行 SQL
• 无需网络：所有操作都在本机运行
• 原生支持 AI：专为 AI 编码 Agent（Claude Code、Cursor、GitHub Copilot）设计

适用场景

✅ 发布迁移前 — 捕获未使用 CONCURRENTLY 的 CREATE INDEX、危险的类型变更、易变默认值
✅ 审查慢查询 — 检测 SELECT *、过深的 OFFSET、无界写入、未建立索引的谓词
✅ 分析 EXPLAIN 计划 — 发现大型顺序扫描、行数估算错误、排序溢出和过高的循环次数
✅ 推荐索引 — 为 WHERE 子句中的列获取保守的 DDL 候选方案

---

使用场景

1. AI Agent 代码审查

你的 Agent 编写迁移，Database Doctor 会在提交前审查。

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. 提交前检查

在危险的迁移进入 CI 之前将其发现。

向你的 AI 提问：“检查 db/migrations/ 中的所有迁移是否安全”

Database Doctor 会检查每个文件并报告：

• 破坏性 DDL（DROP、TRUNCATE）
• 会阻塞操作的索引创建
• 会重写表的列变更
• 未使用 NOT VALID 的约束验证
• 无法容纳 CONCURRENTLY 操作的事务

3. 查询优化

在性能问题影响生产环境之前将其发现。

你的 Agent 会生成：

SELECT * FROM orders 
WHERE LOWER(email) = '[email protected]' 
OFFSET 10000 
LIMIT 20;

Database Doctor 会标记：

• SELECT_STAR：通配符投影使模式与调用方耦合
• FUNCTION_PREDICATE：LOWER() 可能无法使用 email 上的索引
• DEEP_OFFSET：Offset 10000 会丢弃许多行，应使用键集分页

4. EXPLAIN 执行计划审查

提交慢查询的执行计划以供分析。

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

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

Database Doctor 会检测：

• 大型表上的顺序扫描
• 行数估算错误（偏差达到 10 倍或以上）
• 排序操作溢出到磁盘
• 嵌套连接中的循环次数过多

---

检查内容

迁移安全性（check_migration）

检查项	严重性	检测内容
DESTRUCTIVE_DDL	高	DROP TABLE/SCHEMA/DATABASE、TRUNCATE
COLUMN_TYPE_CHANGE	高	ALTER COLUMN ... TYPE（重写表并持有强锁）
BLOCKING_INDEX	中	未使用 CONCURRENTLY 的 CREATE INDEX（会阻塞写入）
CONCURRENT_INDEX_TRANSACTION	高	在 BEGIN/COMMIT 中使用 CONCURRENTLY（无效）
UNIQUE_INDEX_DATA	中	UNIQUE 索引要求现有数据兼容
NOT_NULL_CHANGE	中	SET NOT NULL 或 ADD COLUMN NOT NULL（会扫描表）
CONSTRAINT_VALIDATION	中	未使用 NOT VALID 的 ADD FOREIGN KEY / CHECK
VOLATILE_DEFAULT	高	使用 random()、clock_timestamp()、nextval() 的 DEFAULT
CASCADE	高	CASCADE 可能影响依赖对象

查询分析（analyze_query）

检查项	严重性	检测内容
SELECT_STAR	低	通配符投影会增加耦合
UNBOUNDED_WRITE	高	不带 WHERE 的 UPDATE/DELETE
DEEP_OFFSET	中	大 OFFSET 会丢弃行，应使用键集分页
FUNCTION_PREDICATE	中	WHERE 中的函数可能无法使用索引
UNORDERED_LIMIT	低	不带 ORDER BY 的 LIMIT 会产生不稳定结果
CROSS_JOIN	中	显式 CROSS JOIN 会使行数倍增
NULL_NOT_IN	中	带有 NULL 的 NOT IN 子查询可能产生意外结果
RANDOM_SORT	中	ORDER BY random() 可能需要对所有行排序

EXPLAIN 执行计划分析（explain_plan）

检查项	严重性	检测内容
LARGE_SEQ_SCAN	中	估算行数达到 10,000 行或以上的顺序扫描
ROW_ESTIMATE_ERROR	中	估算行数与实际行数相差 10 倍或以上
SORT_SPILL	中	排序溢出到磁盘（增大 work_mem）
HIGH_LOOPS	中	计划节点执行 1000 次或以上

---

对比

截至 2026 年 10 月。所有比较均基于公开文档，并谨慎表述。

功能	Database Doctor	MigrationPilot	Locksmith	Ballast	DBHub
离线分析	✅ 无需连接数据库	✅ 可选	✅ 无需连接数据库	❌ 需要数据库	❌ 连接数据库
迁移检查	✅ 9 条迁移规则	✅ 112 条规则	✅ 9 条规则 + 重写	✅ Squawk 的超集	❌ 不是检查工具
查询分析	✅ 8 种查询模式	❌ 仅迁移	❌ 仅迁移	❌ 仅迁移	✅ 通过执行实现
EXPLAIN 计划分析	✅ 4 项计划检查	❌	❌	❌	✅ 通过 EXPLAIN 实现
索引建议	✅ 保守的候选项	❌	❌	❌	❌
MCP 服务	✅ 5 个工具	✅ 4 个工具	✅ 3 个工具	⚠️ 不明确	✅ 多数据库网关
无需凭据	✅ 从不连接	⚠️ 可选	✅ 从不连接	❌ 需要 DSN	❌ 需要连接
AI Agent 集成	✅ 原生支持 MCP	✅ MCP + CLI	✅ 原生支持 MCP	⚠️ MCP 支持情况不明确	✅ 多数据库 MCP
自动修复	❌ 仅提供建议	✅ 20 项自动修复	✅ 可直接粘贴的重写方案	⚠️ 不明确	❌
PostgreSQL 专用	✅ 优先支持 PostgreSQL	✅ 仅支持 PostgreSQL	✅ 仅支持 PostgreSQL	✅ 仅支持 PostgreSQL	❌ 多数据库
许可证	MIT	MIT	MIT	MIT	MIT

我们的差异化优势：

• 覆盖面最广：迁移 + 查询 + EXPLAIN 计划 + 索引建议（一个工具涵盖 4 项能力）
• 零配置：无需数据库、凭据或配置，即可检查尚未提交的代码
• 隐私优先：完全离线，不会向任何地方发送数据
• 原生支持 PostgreSQL：不基于正则表达式，可处理注释、字符串、美元引号和嵌套块
• 轻量：除 MCP SDK 和 Zod 外，零依赖

适用替代方案的场景：

• MigrationPilot：需要 112 条规则、自动修复、VS Code 扩展或带 SARIF 的 GitHub Action
• Locksmith：需要可直接粘贴的安全重写方案和锁矩阵文档
• Ballast：需要按真实表大小加权的负载感知分析（需要连接数据库）
• DBHub：需要连接实时数据库以进行探索和受限 SQL 执行

---

工具

Database Doctor 为 AI Agent 提供 5 个 MCP 工具：

工具	输入	输出
analyze_query	sql（字符串）	SQL 反模式，包含严重程度、消息、建议和语句编号
check_migration	sql（字符串）	破坏性 DDL、锁风险、事务冲突和约束验证问题
suggest_indexes	sql（字符串） existingIndexes（可选数组）	保守的索引 DDL 候选项（绝不会应用，需通过 EXPLAIN 验证）
explain_plan	plan（JSON 字符串）	大范围扫描、行数估算错误、排序溢出和高循环次数
health_report	queries（可选数组） migrations（可选数组） plans（可选数组）	对所提供材料进行汇总审查（不代表实时数据库健康状况）

所有工具均为只读、幂等，且无需身份验证。

报告包含：

• code：问题类型的稳定标识符
• severity：high、medium 或 low
• message：问题说明
• recommendation：修复建议
• statement：多语句 SQL 中对应的语句（从 1 开始计数）

---

示例提示词

针对迁移：

"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?"

针对查询：

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

针对 EXPLAIN 计划：

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

针对索引建议：

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

针对汇总审查：

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

与开发工作流集成：

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

---

局限性

Database Doctor 使用的是启发式静态分析，并非完整的 PostgreSQL 解析器，也不能证明操作安全。

擅长处理的内容

✅ 注释（单行 -- 和嵌套块注释 /* */）
✅ 字符串字面量（包括带转义的 E'...'）
✅ 美元引号字符串（$$、$tag$）
✅ 带引号的标识符（"column_name"）
✅ 常见的 DDL 和 DML 模式

已知限制

⚠️ 并非完整的 SQL 解析器：复杂的 CTE、嵌套作用域和不常见的 DDL 可能导致误报或遗漏问题
⚠️ 没有架构元数据：无法验证列是否存在、列的类型或有哪些索引
⚠️ 索引推断较为保守：仅支持一张未加引号的表，不支持联接、子查询或复合索引优化
⚠️ 不分析存储过程正文：不会检查函数、DO 块和动态字符串中的 SQL
⚠️ 不执行查询：无法测量实际查询时间、锁持续时间或真实的执行计划开销
⚠️ 优先支持 PostgreSQL：未经 MySQL、SQL Server、Oracle 或其他方言测试

发现的含义

✅ 检测到问题：应用前请检查具体模式
⚠️ 未发现问题：这并不意味着 SQL 安全、性能良好或符合 PostgreSQL 语法
⚠️ 未发现问题并不代表获得授权，不能据此在生产环境中运行迁移

在生产环境使用前，务必先在安全环境中测试迁移。

---

开发

要求： Node.js >=22.18（推荐 Node 24）

# 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

**测试覆盖范围：**53 项核心测试，涵盖：

• SQL 屏蔽（注释、字符串、美元引号、带引号的标识符）
• 查询分析（全部 8 条规则）
• 迁移检查（全部 9 条规则）
• EXPLAIN 执行计划解析与分析
• 索引建议逻辑
• 健康报告汇总

**CI：**GitHub Actions 会在每次推送和 PR 时运行类型检查、测试、构建、集成测试和软件包验证。

---

作者的更多 MCP 服务

属于 petrovicistefan MCP 套件 — 为 AI 编码 Agent 提供本地优先的防护措施。

此系列中的所有工具均具备以下特点：

• ✅ 本地优先：所有操作都在你的计算机上运行
• ✅ 只读：不会执行破坏性操作（明确选择启用的情况除外）
• ✅ 无需 API 密钥：无需账户，不收集遥测数据，也不会发起网络调用（除非选择启用）
• ✅ 面向 AI 原生构建：专为 AI 编码 Agent 打造

服务	用途
mcp-security-guard	审计 MCP 服务，检查工具投毒、 rug pull 和泄露的密钥（OWASP MCP Top 10）
mcp-cost-optimizer	在昂贵的云服务模式进入生产环境前将其检测出来
mcp-database-doctor	捕获危险的 PostgreSQL 迁移和慢查询（你正在查看此项目）
mcp-dependency-doctor	查找过时的依赖项、CVE 和许可证问题
mcp-seo-auditor	审计网页中的 SEO 和无障碍问题
mcp-api-guardian	根据最佳实践验证 REST API 设计
mcp-marketplace	浏览和发现此系列中的所有 MCP 服务

---

商业路线图

永久免费：

• 本地查询、迁移和 EXPLAIN 执行计划分析
• 全部 5 个 MCP 工具
• 无使用限制
• 无遥测数据

Pro 版（计划推出，可选择启用）：

• 历史记录（前后对比）
• CI 策略和高级建议
• 托管 HTTP API（用于非 MCP 集成）
• 仅为托管路径通过控制平面设置配额

Team 版（计划推出，可选择启用）：

• 共享迁移策略
• 集中式报告
• 全范围查询分析

**本地工具将永远免费并支持离线使用。**付费功能仅为附加功能，且需明确选择启用。

---

贡献

欢迎贡献！请先阅读 CONTRIBUTING.md。

适合初次贡献的事项：

• 为误报或漏报添加测试用例
• 改进文档和示例
• 添加对更多 PostgreSQL 版本的支持
• 扩展查询或迁移规则

目前暂不接受：

• 在没有明确用例的情况下，支持其他数据库（MySQL、SQL Server 等）
• 基于网络的功能（坚持本地优先）

贡献指南 · 未解决的问题 · 报告误报

---

许可证

MIT © Stefan Petrovici

详情请参阅 LICENSE。

---

关于作者

我是 Stefan Petrovici：热爱 IT，是一位丈夫和父亲。我独自构建了 Database Doctor 和整套 MCP 工具集。我正在找工作。

我从头到尾构建 Web 应用——前端、后端、API 和部署——也很乐意参与其他需要开发的项目。这个仓库展示了我的工作方式：测试、CI、细致的文档和对细节的关注。

我也开发 WordPress 和 WooCommerce 插件，可在 pluginsforstores.com 获取。

如果贵团队正在招聘，欢迎写信至 [email protected]。

---

⭐ 支持此项目

觉得这个项目有用？给此仓库点个星！

GitHub 星标有助于其他开发者发现这个项目，也方便你稍后再查看。感谢你支持开源！

---

Database Doctor 与 PostgreSQL、Anthropic 或本文提及的任何其他厂商均无关联。