postgres-diagnostics

使用 pgbot 诊断 PostgreSQL

pgbot 是一个只读的 Postgres 诊断工具。它的检查结果由确定性地计算得出（由 Go 计算，而非模型），并且绝不会写入数据库。请将 pgbot 的输出视为事实依据。你的任务是运行正确的命令，然后解读结果、确定优先级并提出建议——绝不能凭空编造诊断结果，也不能对数据库执行操作。

何时使用此技能

• “为什么我的数据库很慢”“我应该优化什么”“我的 DB 状况健康吗？”
• “哪些索引可以删除”“是什么占用了所有磁盘空间”“autovacuum 跟得上吗？”
• “哪个查询拖垮了数据库”“我应该重新调整什么吗？”
• 任何有关 Postgres 性能、健康状况、膨胀、索引、清理或配置的问题。

如何运行

如果已连接 pgbot MCP 服务，请调用其工具：inspect（从这里开始）、top_queries、vacuum_health、unused_indexes、why。这些工具会返回稳定的 JSON。 （logs、waits、activity、erd 和 report 命令目前仅支持 CLI——请通过 shell 运行。）

否则请运行 CLI。 它需要一个具备读取权限的角色的连接字符串（最好具有 pg_monitor）。根据问题选择相应命令：

问题	命令
开放式问题／“状况健康吗”	pgbot inspect "$DSN"（健康评分 + 按严重程度从高到低排列的检查结果）
完整详情	pgbot inspect "$DSN" --full
“是什么拖垮了数据库？”	pgbot queries "$DSN"（按总耗时排序；使用 --by-calls 重新排序）
“是什么占用了磁盘空间／哪些表最大？”	pgbot tables "$DSN"（大小 + 顺序扫描与索引扫描对比 = 缺失索引预警）
“autovacuum 跟得上吗？”	pgbot vacuum "$DSN"
“哪些索引可以删除？”	pgbot indexes "$DSN"
“我应该重新调整配置吗？”	pgbot tune "$DSN"
“为什么现在就很慢？”	pgbot why --duration 10s "$DSN"（实时采样等待 → 基于证据判定原因：锁竞争、IO、CPU 或客户端；证据不足时不会猜测）
“有哪些连接／正在运行什么？”	pgbot activity "$DSN"（实时会话：PID、状态、等待、时长、已清理的 SQL）
“数据库时间都花在哪里？”	pgbot waits --duration 10s "$DSN"（采样等待类别；只有证据持续充分时才指出阻塞者）
“自昨天以来有什么变化？”	pgbot why "$DSN" / pgbot diff --since 24h（离线分析已存储的快照）
“服务器日志里有什么？”	pgbot logs "$DSN"（使用 --live 持续跟踪，使用 --level error 或 --level audit 筛选；需要额外授权，缺少时会显示所需授权）
“数据库架构是什么样的？”	pgbot erd "$DSN"（使用 --mermaid 生成可渲染的图表，使用 --html > schema.html 生成交互式文件）
供人阅读的完整报告	pgbot report "$DSN" > report.html（自包含页面：检查结果、查询、索引、等待）
供解析的机器可读输出	pgbot inspect "$DSN" --json

对于大型或远程数据库，请添加 --timeout 60s。

首次运行——缺少前置条件时

不要停下来，也不要自行变通；每项缺失条件都有对应的解决方法：

• pgbot 不在 PATH 中： 安装它——curl -fsSL https://pgbot.dev/install | sh （或者运行 brew install pgrundev/tap/pgbot，也可以通过 npx @pgbot/cli 免安装运行）。请通过常规权限提示运行，以便用户 看到这条命令。
• 没有连接字符串： 检查 $DATABASE_URL，然后向用户索取。 绝不要猜测或自行拼凑凭据。
• 角色或扩展不符合要求： 如果已安装的 pgbot 支持 init，请运行 pgbot init --verify "$DSN"——它会检查 pg_monitor 和 pg_stat_statements， 并指出每项所需的修复方法。旧版本会在连接时报告相同的缺项。 如需创建只读角色，请使用 pgbot init 生成 SQL（或参阅 pgbot README 的 Setup 部分），然后交由用户以管理员身份运行——绝不要自行执行：pgbot 绝不写入， 你也一样。

规则 — 不可妥协

1. 发现必须有事实依据。 不要编造 pgbot 未报告的数字、表格、索引或查询 ID。如果 pgbot 没有测量某项指标，就说明 pgbot 需要收集哪些信息才能查明。
2. 在建议中保留所有注意事项。 例如：“未使用索引”扫描的计数按节点统计——在主节点上看似未使用的索引，副本可能仍在使用。pgbot 会标记这一点；没有注明注意事项时，绝不要建议删除索引。（pgbot 的 tables/indexes 和 JSON 会显示复制状态——请检查。）
3. 绝不执行用户的查询来诊断问题。 不要使用 EXPLAIN ANALYZE，也不要“只运行一次语句来计时”。只能建议安全且不执行查询的步骤（可以使用不带 ANALYZE 的 EXPLAIN；它不会运行查询）。
4. 按影响而不是数量排序。 首先处理风险（距事故发生的时间：事务 ID 回卷、占用 WAL 的复制槽、磁盘即将写满）。然后再处理最大的延迟或存储收益。回收 9 GiB 未使用索引的收益，可能还不如解决一个占用数据库时间 60% 的查询——请说明先做哪件事，以及原因。
5. 绝不写入数据库。 pgbot 只读；你只提供建议，不采取行动。把准确的 DROP INDEX CONCURRENTLY / ALTER / VACUUM 语句交给用户，让他们自行运行。
6. 对低置信度结论保留余地。 置信度低于 0.5 的发现只能表述为一种可能（“可能”“或许”），不能当作定论。
7. 标明证据类型。 回答中要清楚区分以下三类内容：pgbot 数据证实的发现、仍需审核（代码、副本或工作负载）的建议，以及因缺少统计信息或权限而无法得出的结论。

输出格式

1. 一句话概述健康状况。
2. 按严重程度从高到低列出最多约 3 个问题。对每个问题：问题及 pgbot 的数值 → 仅当数据（变化量/事件）支持时才说明可能原因 → 给出安全、具体的建议，并在建议中注明注意事项。
3. 简要说明哪些方面状况良好，让用户知道检查了什么。

解读信号

• tables： 大表若有大量 seq scans 且 idx scans 很少，可能缺少索引——请结合 queries 交叉核查（如果某个排名靠前的查询正在筛选该表，就能佐证这一点）。
• queries： share 表示占数据库总执行时间的百分比。单个查询占比超过约 30% 时，通常就是真正的热点路径；删除索引无法解决这个问题。
• vacuum： due? yes 且最近一次自动清理时间很久以前或为 never，说明自动清理跟不上——这是膨胀的早期信号，后续可能导致事务 ID 回卷。
• 复制槽发现： 不活跃的复制槽会保留 WAL 并导致磁盘写满；应将其视为距事故发生时间的问题，而非表面问题。

安全与隐私

pgbot 始终只读。除 pgbot explain / pgbot ask 外，不会有任何数据离开本机；这两个命令会将不含个人身份信息的发现（规范化的查询文本，不含字面值）发送给大模型，并会事先说明这一点。请使用具有 pg_monitor 权限的角色；切勿在可能泄露凭据的地方粘贴生产环境超级用户凭据。