sarteta/postgres-incident-toolkit
GitHub: sarteta/postgres-incident-toolkit
面向生产环境 PostgreSQL 事件的只读 CLI 诊断工具，30 秒内输出覆盖长查询、锁等待、复制延迟等七大维度的结构化报告，同时生成 Markdown 运维手册和 AI 可消费的 JSON 数据。
Stars: 0 | Forks: 0
# postgres-incident-toolkit
用于生产环境 Postgres 事件响应的 CLI 工具。当凌晨 3 点出现紧急情况——复制延迟、查询堆积、死锁、膨胀占用磁盘——这个工具能在 30 秒内为你提供一份结构化报告，而不是让你敲 30 分钟的 `psql` 命令。
设计上为只读。该工具不包含任何 `DROP`、`KILL`、`VACUUM` 操作。它只告诉你哪里出了问题；你来决定怎么做。
```
flowchart LR
DBA([DBA / oncall]) -- pgincident scan --> T[postgres-incident-toolkit]
T -- read-only SQL --> DB[(Postgres prod)]
DB --> T
T --> M[Markdown runbook]
T --> J[JSON for AI agents]
M --> DBA
J --> Claude([Claude / MCP])
```
## 它能检测什么
| 检测器 | 显示内容 |
|---|---|
| `long_queries` | 运行超过 N 分钟的活跃查询（默认 5 分钟） |
| `lock_waits` | 等待锁超过 N 秒的会话及其持有者 |
| `replication_lag` | 延迟超过 N 秒的备用副本及上次 WAL 回放时间 |
| `bloat_top_tables` | 按预估膨胀率（%）排名靠前的表（无需 pgstattuple） |
| `idle_in_transaction` | 卡在 `idle in transaction` 状态并消耗 xid 的会话 |
| `connection_saturation` | 每个数据库的连接数与 `max_connections` 的对比 |
| `unused_indexes` | 自上次统计重置以来扫描次数为 0 的索引 |
## 安装
```
pip install postgres-incident-toolkit
# 或从源码：
pip install git+https://github.com/sarteta/postgres-incident-toolkit
```
## 在事件期间使用
```
# 扫描所有检测器，写入 Markdown + JSON
pgincident scan \
--dsn "postgresql://oncall:***@db-prod.internal:5432/app" \
--out-md /tmp/incident-2026-05-06.md \
--out-json /tmp/incident-2026-05-06.json \
--long-query-min 5 \
--lock-wait-sec 30
```
输出摘要：
```
# Postgres 事故报告 — 2026-05-06 14:32 UTC
- DB: db-prod (PostgreSQL 16.4)
- Detectors run: 7
- Findings: 3 critical · 4 warning · 0 info
## CRITICAL — Replication lag (standby-1)
- Lag: 487 seconds (threshold: 60)
- Last WAL replay: 2026-05-06 14:24 UTC
- Standby last seen: 2026-05-06 14:32 UTC
- Likely root cause: long-running query on primary blocking WAL replay
- See finding `long_queries` below — query running 12 min on `app_db`.
## CRITICAL — 长查询
- pid: 187234
- duration: 12 min
- query: SELECT * FROM events WHERE ts > $1 ORDER BY ts; (no index)
- application: reporting-cron
- backend_xmin held: yes
```
## 搭配 mcp-postgres-doctor 使用
本仓库是 **CLI**。其同级项目
[mcp-postgres-doctor](https://github.com/sarteta/mcp-postgres-doctor)
将这些扫描器作为 MCP 工具暴露出来，以便 AI 代理（Claude, Cursor）在对话中运行它们：
```
> Hey, db-prod is alarming. Anything obvious?
[claude calls long_queries + replication_lag + lock_waits]
Yes — replication lag at 487s on standby-1.
Root cause: a 12-minute query on the primary holding xmin.
Query: SELECT * FROM events WHERE ts > $1 ORDER BY ts;
Recommend: kill pid 187234, then add an index on events(ts).
```
## 安全性
| 关注点 | 本工具的处理方式 |
|---|---|
| 这个工具会杀进程吗？ | 不会。工具以 `list_*` / `top_*` / `summarize_*` 开头。没有 `kill_pid_tool`。这是设计初衷。 |
| 它会造成锁吗？ | 不会。所有查询都针对 `pg_stat_*` 视图和 `pg_class`——不涉及用户表，没有共享锁。 |
| 角色需要什么权限？ | `pg_monitor` 就足够了。或者授予 `pg_stat_activity`、`pg_stat_replication`、`pg_locks`、`pg_class`、`pg_index`、`pg_stat_user_indexes` 的 SELECT 权限。 |
| 它适用于托管型 Postgres 吗？ | 是的——适用于 RDS、Aurora、Cloud SQL。在没有 `pgstattuple`（扩展）的情况下，某些膨胀估算值是近似的。 |
## 相关资源
- [`postgres-production-playbook`](https://github.com/sarteta/postgres-production-playbook) — 按症状索引的诊断 SQL 查询
- [`mcp-postgres-doctor`](https://github.com/sarteta/mcp-postgres-doctor) — 作为 AI 代理 MCP 工具的同类检测器
## 许可证
MIT (c) 2026 Santiago Arteta
标签：API集成, DBA工具, Markdown报告, MCP, PostgreSQL, Python, 只读安全, 可观测性, 告警分析, 复制延迟, 大模型集成, 开源, 性能监控, 慢查询检测, 故障排查, 数据库诊断, 数据库运维, 文档结构分析, 无后门, 无线安全, 查询优化, 测试用例, 生产环境, 空间膨胀, 运维自动化, 连接数监控, 逆向工具, 锁等待