slowplan

slowplan：这个 PostgreSQL 查询为什么这么慢？

一个 MCP 服务和 CLI，可读取 PostgreSQL EXPLAIN 输出，告诉你耗时所在以及优先尝试什么。它只根据计划文本工作，因此不会连接数据库。

冗长的 EXPLAIN ANALYZE 很难读懂，也很容易判断失误：Postgres 在并行计划中报告的是每个工作进程的平均值，而看起来最慢的节点往往并非耗时所在。slowplan 会计算每个步骤的实际耗时，并按问题严重程度排序，例如丢弃行的顺序扫描、错误的行数估算、溢出到磁盘的排序和哈希，以及多次运行的嵌套循环。

可以向 Agent 提什么问题

• “这个 Postgres 查询很慢。这是 EXPLAIN ANALYZE 输出。”
• “为什么规划器在这里执行顺序扫描？”
• “我加了一个索引。它有帮助吗？”
• “这个计划里最该先修复什么？”

安装

作为 Claude Code 插件：

claude plugin marketplace add GillMacedo/slowplan
claude plugin install slowplan@slowplan-marketplace

作为 MCP 服务，供任何客户端使用：

{"mcpServers": {"slowplan": {"command": "npx", "args": ["-y", "[email protected]", "serve"]}}}

作为 CLI，要求 Node 18 或更高版本：

npx slowplan review plan.txt

或者使用 Go 1.27 或更高版本：go install github.com/GillMacedo/slowplan@latest。

用法

使用 EXPLAIN (ANALYZE, BUFFERS) <your query> 获取计划，格式可以是文本或 JSON。**ANALYZE 会实际运行查询，**因此对于任何写入操作，都要放在会回滚的事务中执行。

以下是来自 PostgreSQL 17 的真实计划，表名为虚构：

$ make demo
Execution 48.9 ms, planning 0.3 ms

Where the time goes:
   80.8%      39.5 ms  Bitmap Heap Scan on orders
    3.9%       1.9 ms  Bitmap Index Scan on orders_status_idx

HIGH   PG102 Bitmap Heap Scan on orders
  The index doesn't cover the whole filter. Read and threw away 84857 rows to keep 857, using filter (bucket = 7).
  Try: Candidate to test: CREATE INDEX CONCURRENTLY ON orders (bucket), or add these columns to the index in use.

These are leads from one run. Test a fix on realistic data before relying on it.

要检查改动，请比较改动前后的计划：

slowplan compare before.txt after.txt

在 examples/ 中的一个真实示例里，添加 slowplan 建议的索引后，查询耗时从约 25 ms 降到了 0.1 ms。

添加 --json 以输出 JSON，或添加 --fail-on high 以在 CI 中以代码 1 退出。使用 - 从标准输入读取。

可发现的问题

规则	可发现的问题
PG101	顺序扫描丢弃了读取的大部分行
PG102	索引未覆盖整个筛选条件
PG103	连接产生行后又将其丢弃
PG104	位图重检丢弃了许多行
PG105	行数估算偏差达到 10 倍或以上
PG106	嵌套循环的内侧运行了 1,000 次或以上
PG107	排序溢出到磁盘
PG108	哈希表被拆分为多个磁盘批次
PG109	并行工作进程少于计划数量
PG110	仅索引扫描仍频繁访问表
PG111	位图变成有损位图
PG112	从共享缓冲区外读取约 80 MB 或更多数据
PG113	规划耗时超过查询运行时间
PG114	JIT 耗时达到 100 ms 或以上

严重程度取决于查询耗时占比：高表示 20% 或以上；低表示低于 5% 或低于 1 ms。这些阈值是经验判断。

MCP 工具

工具	功能
postgres_plan_review	检查一个计划，输入可以是文本或文件
postgres_plan_compare	比较改动前后的计划

限制

• 建议的索引只是候选项。 执行计划展示的是一条查询和一组值，不会显示你的其他索引，也不会显示索引对写入的成本。请使用真实的数据进行测试。
• 一次运行不算基准测试。 缓存未命中或服务器繁忙都会影响耗时。
• 它无法查看锁、网络耗时或执行计划之外的任何内容。只有估算值的执行计划没有任何实测数据，slowplan 会说明这一点。
• **并行执行计划中的耗时是估算值，**因为 Postgres 报告的是各工作进程的平均值。
• 仅支持 PostgreSQL。其他工具的文本执行计划或经过大量编辑的执行计划可能无法解析。JSON 格式最可靠。
• 执行计划可能包含查询中的值。slowplan 会在你的设备上运行，但 MCP 客户端会将工具结果发送给其模型。

常见问题

如何阅读 EXPLAIN ANALYZE 的输出？ 将其交给 slowplan，它会展示耗时都花在了哪里。

为什么 Postgres 会执行顺序扫描？ 通常是因为没有合适的索引，或者筛选条件会保留太多行，导致索引无济于事。PG101 会显示有多少行被过滤掉。

如何判断排序或哈希操作是否在使用磁盘？ PG107 和 PG108 会标记这些情况。

这与 pev2 或 postgres-mcp 有何不同？ pev2 是面向用户的可视化工具。postgres-mcp 会连接到实时数据库。slowplan 会根据执行计划文本向 Agent 提供按优先级排序的发现结果，且无需访问数据库。

测试情况

PG101、PG102、PG104 至 PG112 已使用来自 PostgreSQL 17 数据库的真实执行计划进行测试，这些计划使用了虚构的表，以 JSON 和文本格式存放在 examples/ 中。PG103、PG113 和 PG114 仅使用编写的示例进行测试。MCP 工具调用已通过 MCP Inspector 测试。它尚未用于真实的生产查询。

贡献

欢迎个人以及与 AI Agent 合作的贡献者参与。请参阅 CONTRIBUTING.md。适合新手的 issue 列在此处。

Pull request 的处理方式

1. 创建 PR。 Fork 仓库，在分支上开展工作，并确保只包含一项更改。标题应说明用户会看到什么变化，因为它会成为变更日志条目：feat: 会列在 Added 下，fix: 会列在 Fixed 下。
2. 自动检查。 代码更改必须附带测试，且 make test 必须通过。超过 30 行的更改必须关联一个未关闭的 issue（Closes #<number>），且 PR 的更改行数不得超过 800 行。如果缺少内容，系统会通过评论告知你需要修正的地方。
3. 审查。 Claude 会自动审查每个 PR。代码 PR 还会接受安全审查，并在沙盒中进行测试。之后，审查流程会合并 PR 或要求修改。更改 CI、Agent 设置、npm 或 Python 依赖项、供应代码或构建文件的 PR 无法通过此流程合并，系统会通过评论说明原因。安全审查未通过的更改也同样无法合并。
4. 发布。 合并后会影响用户安装内容的更改，会在大约两小时内发布为新版本，并附带 GitHub Release；如果项目有 npm 包，也会一并发布。文档和 CI 更改会留待下次发布。

AI 使用说明

本项目大部分由 Claude Code 生成，并由维护者审查。

关于我

我是 Giulliano Macedo，在 GoTech Solutions 开发开发者工具。欢迎关注或联系我：

• GitHub：GillMacedo
• LinkedIn：giulliano
• X：@giumacedo

如果 slowplan 帮你找到了慢查询，点个星标能帮助其他人发现它。

---

由 Giulliano Macedo、GoTech Solutions 打造 · LinkedIn · X