| name | pg-stat-snapshot |
| description | 为 PostgreSQL 实例建立统计信息快照采集、存储、差值计算与历史清理的基础设施。当用户提到"快照采集"、"pg_stat_statements 差值分析"、"统计信息历史留存"、"TOP SQL 分析基础设施"、"表/索引 DML 增量分析"、"性能诊断基础设施"、"stat snapshot"、"需要两个时间点对比统计信息"、或提供了 PostgreSQL 实例连接信息（host/port/user/password）并希望搭建可重复调用的性能快照系统时触发。即使用户只说"帮我给这个库建个统计快照"或"我要能对比两个时刻的 pg_stat_statements"，也应使用本技能。本技能只负责基础设施搭建、采集、差值计算与清理，不产出最终分析报告——报告类需求应转交 pg-top-sql-analyze / pg-large-table-optimize / pg-bloat-root-cause 等下游技能。 |
| 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-stat-snapshot)
为一个 PostgreSQL 实例建立可重复调用的统计信息快照系统：定时采集 pg_stat_* 系列视图到历史表，支持任意两个快照之间的差值计算，并提供按时间/按数量的历史清理能力。这是所有"两阶段采集对比"类性能分析技能（TOP SQL、表膨胀、索引使用率等）的公共基座，其他技能应直接消费本技能建立的历史表，不应重复造轮子。
前置要求
- 已知目标实例的连接信息：host、port、user、password（或已配置
.pgpass / 环境变量 PGPASSWORD）。
- 客户端已安装
psql（用于执行 DDL/DML）；如需在多个数据库间自动遍历，需要能连接到 postgres 库读取 pg_database。
- 目标账号权限：
- 创建
stat_snapshot schema 及表 —— 需要在目标库有 CREATE 权限（超级用户或库 owner 最省事）。
- 读取
pg_stat_statements —— 需要该扩展已在对应库 CREATE EXTENSION pg_stat_statements，且账号有权限查询（PG 14+ 可通过 pg_read_all_stats 角色授权，无需超级用户）。
- 读取
pg_stat_activity 全部字段（含 query 文本）—— 通常需要超级用户或 pg_read_all_stats。
- 不需要联网；所有操作均在目标实例内部完成。
- 权限不足时，不要静默降级，直接输出对应的
GRANT/CREATE EXTENSION 语句让用户以有权限账号执行（见"权限不足处理"一节）。
工作流程
Step 0：连接探测与版本识别
先执行只读探测，禁止在未确认版本前直接跑固定版本的 DDL：
psql "host=<HOST> port=<PORT> user=<USER> dbname=postgres" -Atc "SELECT current_setting('server_version_num'), current_setting('server_version');"
psql "host=<HOST> port=<PORT> user=<USER> dbname=postgres" -Atc "SELECT datname FROM pg_database WHERE datistemplate = false;"
psql "host=<HOST> port=<PORT> user=<USER> dbname=postgres" -Atc "SELECT extname, extversion FROM pg_extension WHERE extname = 'pg_stat_statements';"
根据 server_version_num 决定：
pg_stat_statements 是否含 total_plan_time 等 planning 相关字段（PG 13+ 才有，且需 pg_stat_statements 扩展版本 ≥ 1.8 且 track_planning=on 才有意义）。pg_stat_wal 是否存在（PG 14+）。- 是否存在
pg_stat_activity.query_id（PG 14+）。
若 pg_stat_statements 扩展未安装，输出：
CREATE EXTENSION IF NOT EXISTS pg_stat_statements; -- 需要在 postgresql.conf 中已配置 shared_preload_libraries='pg_stat_statements' 并重启生效
并提示这一步无法绕过（该扩展依赖共享内存预加载，不能只靠 生效，必须确认已重启过）。
