pgbot

这是什么？适合谁？

pgbot 是一个 PostgreSQL 数据库内的可观测性工具：单个静态二进制文件，以只读方式连接数据库，读取 Postgres 自带的统计视图，输出一份”发现优先”的健康报告，并告诉你自上次检查以来发生了什么变化。它没有 Agent、没有外部服务、全程不需要任何写权限——pgbot ask "what's wrong?" 还能在同一份发现之上叠加一层平实的 AI 解读。

适合人群：维护 PostgreSQL 的后端工程师与 DBA、需要在 CI 或定时任务里做库健康巡检的运维、想给 AI Agent 提供数据库只读观测接口的团队。 使用前提：一台 PostgreSQL 数据库、一个只读账号（或具备读取统计视图权限的账号）、类 Unix 或支持运行静态二进制的环境。

快速上手（3 步）

第一步：安装

curl -fsSL https://pgbot.dev/install | sh

安装脚本拉取单个静态二进制文件，无依赖、无守护进程。

第二步：跑第一次巡检

pgbot inspect "postgres://pgbot_ro@host:5432/db"

输出形如：

connected · db.example.com · postgres 17.4 · read-only · 6h20m window
Database health: 82/100
CRITICAL
● transaction-id age 1.8B - 84% toward wraparound
WARNING
● orders queries 3.2× slower (8 -> 26 ms mean)
● 3 unused indexes consume 18 GB
...

第三步：看变化与细节

再次运行 pgbot inspect，它会对比上次结果报告”什么变了”；pgbot inspect --full 展开子系统状态板、分节表格与每条发现的 caveat；--json 输出完整的版本化机器可读契约。

初级用法

• 聚焦命令：pgbot indexes / pgbot queries / pgbot tables / pgbot vacuum 各自钻取一个信号面，比全量报告更快定位问题域。
• AI 解读：pgbot ask "what's wrong?" 用平实语言总结当前发现，pgbot explain 进一步解释术语与指标含义。
• 接入脚本：--json 是版本化契约，直接作为脚本和 Agent 的输入，不必解析人类可读格式。

高级玩法

1. 定时巡检 + 差分告警：cron 每 6 小时跑一次 inspect --json，对 diff 非空的发现（如”查询变慢 3.2ד）接告警渠道。
2. 给 AI Agent 当数据库眼睛：Agent 通过 MCP/工具调用 pgbot inspect --json 与 pgbot ask，以零写权限获得结构化的库健康事实，避免 Agent 直连生产库乱摸。
3. 只读安全审计：利用”全程无写权限”的设计，把 pgbot 作为最小权限账号的标准配置项，巡检账号申请流程即是权限收敛流程。

常见踩坑（5 条）

踩坑 1：连接失败提示权限不足

• 现象：inspect 报统计视图读取错误
• 原因：账号没有 pg_read_all_stats 等统计视图权限
• 解决：为巡检账号授予只读统计权限（如 GRANT pg_monitor TO pgbot_ro）

踩坑 2：健康分数看不懂权重

• 现象：82/100 但不知道扣在哪
• 原因：默认报告是”分级阅读”：分数 + CRITICAL/WARNING/NOTE 分桶 + GOOD 清单
• 解决：用 --full 查看每个子系统的状态板与每条发现的 caveat

踩坑 3：误以为它会改数据库

• 现象：团队评审担心巡检工具风险
• 原因：对”静态二进制 + 只读连接”设计不了解
• 解决：直接说明 pgbot 在任何路径上都无写权限，可网络层再限制为只读端点

踩坑 4：wraparound 发现被忽视

• 现象：transaction-id age 持续升高
• 原因：这是 CRITICAL 级发现——距离事务 ID 回卷（wraparound）84% 属于必须处理
• 解决：立即安排激进的 autovacuum 或手动 VACUUM FREEZE

踩坑 5：AI 问答超出观测范围

• 现象：pgbot ask 回答”不知道”类问题
• 原因：AI 解读只基于同一份发现数据，不是通用数据库助手
• 解决：数据问题走 --full 与聚焦命令，业务问题另找工具

FAQ（5 个常见问题）

Q1：pgbot 免费吗？ A：单二进制安装免费使用；仓库无 LICENSE 标准文件（自定义许可），商用前建议核对许可条款。以 pgbot.dev 官方说明为准。

Q2：和 pgAdmin / pgwatch2 有什么区别？ A：pgAdmin 是图形管理台；pgwatch2 是常驻指标采集+看板。pgbot 是零部署的一次性巡检器：连上、读统计、出报告、退出，适合巡检与 Agent 调用。

Q3：支持哪些 PostgreSQL 版本？ A：基于 Postgres 自带统计视图，演示输出基于 postgres 17.4；具体版本支持矩阵以官方文档为准。

Q4：AI 功能需要额外 API key 吗？ A：pgbot ask/explain 的模型通道与计费方式以官方文档为准，本文未实测；核心 inspect 报告不依赖 AI 也能完整工作。

Q5：会拖慢数据库吗？ A：只读统计视图查询开销很小；极端高负载库建议在从库或低峰期运行。

小技巧（5 条）

1. 先跑基线：新库接入第一天跑一次 inspect 存档，之后的”变化”报告才有参照系。
2. GOOD 清单也看：它点名”验证过是健康的子系统+数值”，能帮你确认覆盖面，而非只盯着告警。
3. JSON 契约别手解析人类格式：脚本一律用 --json，字段有版本号，升级更稳。
4. 聚焦命令做深钻：先 inspect 定位域，再 pgbot queries/indexes 展开，比反复跑全量快。
5. 把 6h20m window 当上下文：报告的时间窗告诉你发现基于哪个观察区间，跨窗口对比要注意基准。

进阶学习建议

• 通读 inspect --full 的每个子系统状态板，建立自己的 Postgres 健康检查清单（wraparound、缓存命中率、复制、锁、死锁）
• 研究 --json 契约的版本化字段设计，学习如何为自己的内部工具定义稳定输出
• 用聚焦命令（vacuum、tables）逐个深挖 Postgres 统计视图（pg_stat_*）背后的原理
• 在 pgbot.dev 跟进 ask/explain 能力演进，评估把它接入你的 Agent 观测工具链

参考链接

• pgbot GitHub 仓库
• pgbot 官网

本文基于公开资料于 2026-08-17 整理，社区指标反映 GitHub 公开数据。独立实测未进行，功能和配置项可能随版本更新而变化，请以官方文档为准。