| name | pg-bloat-root-cause |
| description | PostgreSQL 表/索引膨胀根因诊断专家。当用户提供 PostgreSQL 实例连接信息（主机、端口、用户名、密码）并希望排查表膨胀、索引膨胀、死元组过多、autovacuum 不生效、vacuum 卡住等问题时触发。关键词包括：'表膨胀'、'索引膨胀'、'膨胀根因'、'为什么会膨胀'、'死元组'、'dead tuple'、'autovacuum 没生效'、'vacuum 不清理'、'空间不回收'、'bloat'、'2PC 未提交事务'、'长事务导致膨胀'、'复制槽延迟'、'hot_standby_feedback'、'备库反馈膨胀'、'磁盘空间异常增长排查'。即使用户只说'帮我看看这个库为什么这么大'或'这张表怎么一直变大'，只要涉及 PostgreSQL 实例且怀疑膨胀，也应使用本 skill。本 skill 强调因果链分析而非仅报告膨胀数值：必须把膨胀数据与长事务、未提交 2PC 事务、长查询快照、复制槽延迟、备库 hot_standby_feedback 等根因逐一关联，给出可执行的诊断报告和只读安全的修复建议。 |
| tags | ["PostgreSQL","表膨胀","索引膨胀","膨胀潜在隐患"] |
| 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-bloat-root-cause）
深入诊断 PostgreSQL 表/索引膨胀的根本原因，而不只是报告膨胀量。将膨胀现象与长事务、未结束的 2PC 事务、长时间运行的查询、复制槽延迟、备库 hot_standby_feedback 等阻塞 vacuum 的机制建立因果链，最终产出一份可直接用于修复决策的诊断报告。
前置要求
- 客户端需要能够访问目标 PostgreSQL 实例（主机、端口、用户名、密码，以及可选的备库连接信息）。
- 推荐使用
psql 命令行工具执行只读查询；如果目标环境已安装 psql，直接调用；未安装时按平台执行 apt-get install -y postgresql-client 或 yum install -y postgresql（如为 Anolis/RHEL 系）。
- 若需要精确膨胀大小（而非估算值），目标库需安装
pgstattuple 扩展（CREATE EXTENSION IF NOT EXISTS pgstattuple;）；无权限安装时自动降级为基于统计信息的估算方法（见 references/bloat-estimation.sql）。
- 部分视图（如
pg_prepared_xacts、pg_stat_replication）需要 superuser 或 pg_monitor 角色权限，权限不足时在报告中注明并给出授权命令，不中断整体分析。
- 不要将密码写入磁盘文件或提交到版本库。运行
psql 时通过环境变量 PGPASSWORD 传递密码，仅在当前会话生效；scripts/run_query.sh 已按此方式封装。
- 输出语言：中文。
工作流程
严格按以下四个阶段推进，每个阶段的产出都是下一阶段因果匹配的输入。所有查询语句集中在 references/queries.sql，按章节编号组织，需要哪一节就去查该文件对应编号，避免把全部 SQL 都塞进正文。
阶段一：环境信息采集
连接目标实例后，依次执行 references/queries.sql 中 -- [ENV] 标记的查询，采集：
- PostgreSQL 版本及编译信息（
SELECT version();）。
- 实例角色：
SELECT pg_is_in_recovery();——true 为备库，false 为主库。
- 当前所有数据库及大小（
pg_database + pg_database_size）。
- autovacuum 相关参数：
autovacuum、autovacuum_vacuum_scale_factor、autovacuum_vacuum_threshold、autovacuum_vacuum_cost_delay、vacuum_defer_cleanup_age、idle_in_transaction_session_timeout。
hot_standby_feedback 当前值——如果本实例是主库，记下此项，提示后续阶段需要向用户询问备库信息。
阶段二：膨胀隐患因果链排查
逐项排查以下 6 类根因，每一类都必须输出：是否存在问题 / 严重程度（Critical / Warning / Info）/ 该问题如何导致膨胀。对应查询见 references/queries.sql 中 -- [CAUSE-n] 标记。
1. 长事务检测
筛选 pg_stat_activity 中满足以下任一条件的会话：
- 状态非
idle，且事务开始时间距今 > 5 分钟；
