| name | pg-runtime-risk |
| description | PostgreSQL 高可用架构与运行时风险诊断专家技能。给定实例连接信息（主机、端口、用户名、密码），对实例进行只读全面运行时风险扫描，覆盖事务回卷、序列回卷、冻结风暴、复制延迟（物理/逻辑槽）、WAL 异常与堆积、连接数耗尽、集群单点故障、大对象泄漏、统计信息过时等维度，输出按严重程度分级（🔴严重/🟠警告/🟡关注/🟢正常）的中文预警报告。触发场景包括但不限于："帮我评估一下这个 PG 实例的运行时风险"、"检查一下事务回卷/XID 回卷风险"、"序列要用完了吗"、"冻结风暴"、"复制延迟检查"、"逻辑复制槽是不是堆积了"、"WAL 堆积/归档失败排查"、"连接数是不是要满了"、"too many connections"、"max_connections 告警"、"连接池是不是耗尽了"、"这套集群有没有单点故障"、"大对象是不是泄漏了"、"pg_largeobject 太大了"、"数据库年龄检查"、"autovacuum 是否正常"、"统计信息是不是过时了"、"执行计划突然变差"、"优化器选错了执行计划"、"为什么走了全表扫描"、"analyze 是不是没跑"、"表多久没做 analyze 了"。即使用户只说"帮我看看这个库有没有风险"或提供了连接信息但未指明具体维度，也应触发本技能进行全面扫描。 |
| tags | ["PostgreSQL","运行时潜在风险分析","连接数耗尽","事务回卷","序列回卷","冻结风暴","复制延迟","逻辑复制槽推进延迟","逻辑复制槽未激活","归档日志异常","WAL堆积","大对象泄露","统计信息过时"] |
| platform | ["claude-code","cursor"] |
| author | digoal |
| version | 1.0.0 |
| license | GNU General Public License v2.0 |
| homepage | https://github.com/digoal/skills |
PostgreSQL 运行时风险诊断（pg-runtime-risk）
对一个 PostgreSQL 实例做全维度只读运行时风险扫描：事务回卷、序列回卷、冻结风暴、
复制延迟、WAL 异常、连接数耗尽、集群单点故障、大对象泄漏、统计信息过时，
输出分级中文预警报告。
前置要求
- 环境需安装 PostgreSQL 客户端
psql，且版本 ≥ 10（psql --version 验证）。
第二部分序列检查依赖 \gset + \if :{?var} 条件判断语法，该语法在 psql 10 才引入，
低版本客户端会报语法错误，需提示用户升级 psql 客户端（与目标数据库服务端版本无关）。
- 连接账号建议具备
pg_monitor 角色或超级用户权限（pg_ls_waldir() 等函数需要更高权限，
权限不足时会自动优雅降级并在报告中注明"因权限不足跳过"，不会导致整体扫描失败）。
- 密码仅通过
PGPASSWORD 环境变量传递，不接受用户以明文形式粘贴到会话记录中长期保留，
不写入任何脚本文件、不打印到日志、不落盘。
- 本技能全程只读：所有查询均包裹在
SET SESSION CHARACTERISTICS AS TRANSACTION READ ONLY
的事务中执行，不会对目标实例产生任何写操作。
工作流程
Step 0：获取连接信息
向用户确认：主机（host）、端口（port，默认 5432）、用户名（user）、密码、
目标数据库（database，默认 postgres，若实例有多个业务库，事务回卷等检查需遍历所有库）。
密码通过环境变量传递，例如：
export PGPASSWORD='xxxxxx'
不要将密码写入任何会保存的文件或命令历史。
Step 1：执行只读扫描
调用 scripts/run_scan.sh：
PGPASSWORD='xxxxxx' bash scripts/run_scan.sh -h <host> -p <port> -U <user> -d <database> -o <output_dir>
该脚本会自动完成：
- 第零部分：版本、启动时间、运行角色、关键参数、复制槽、WAL 接收状态
- 第一部分：数据库/表级 XID 年龄、autovacuum freeze 进度
- 第二部分：所有非循环序列的剩余调用次数与风险等级（通过
\gset + 动态 SQL
在只读事务内一次性计算，无需 Agent 再做算术）
- 第三部分：冻结风暴分桶统计
- 第四部分：物理复制延迟、逻辑复制槽状态
- 第五部分：归档状态、WAL 目录堆积统计
- 第六部分：连接数占用总览、按数据库/用户拆分、长时间 idle in transaction 明细
- 第八部分：大对象总量与疑似引用列
- 第九部分：全表统计信息新鲜度（
n_mod_since_analyze 占触发阈值比例）、
从未分析过的表清单
脚本对每个检查项都做了权限/版本容错：若某项因权限不足或函数不存在而失败，
会在对应 <file>.csv.err 中留痕，并在标准错误输出提示，视为正常的优雅降级，
不代表整体扫描失败，继续处理其余项即可。
Step 2：解读结果并分级
逐个读取 <output_dir>/ 下的 CSV 文件，对照 references/thresholds.md 中
每个维度的分级阈值表进行判定。重点：
- 事务回卷：先看
01_database_xid_age.csv 找出年龄最高的库，
再结合 01_table_xid_age_top20.csv 定位阻碍该库年龄下降的具体表；
若已进入警告区间，检查 01_vacuum_progress.csv 判断当前是否有 autovacuum
worker 正在处理、能否在回卷前完成。
- 序列回卷： 已直接给出 列，
按严重程度倒序整理；对 为 / 且风险等级较高的，
建议改为 （可用 中的 A4 查询二次确认）。
