| name | pg-perf-insight |
| description | 基于 pg-stat-snapshot 采集的历史快照，为指定时间段生成 AWS Performance Insights 风格的 PostgreSQL 深度性能诊断报告。触发场景：用户给出实例连接信息（host/port/user/密码）+ 快照 schema + 分析时间段，并要求'性能诊断'、'性能分析报告'、'AAS 分析'、'Top SQL 分析'、'等待事件分析'、'数据库负载分析'、'为什么这段时间数据库很慢'、'定位性能瓶颈'、'类似 AWS PI 的报告'。即使用户只说'帮我分析一下昨晚 2-3 点数据库为什么慢'并提供了连接信息，也应触发本技能。 |
| tags | ["PostgreSQL","性能洞察","performance insight","快照分析"] |
| platform | ["claude-code","cursor"] |
| author | digoal |
| version | 1.0.0 |
| license | GNU General Public License v2.0 |
| homepage | https://github.com/digoal/skills |
pg-perf-insight：PostgreSQL 性能诊断报告生成器
给定实例连接信息、快照 schema、分析时间段，从历史快照中定位最佳快照对，计算差值指标，产出一份 AWS Performance Insights 风格的中文深度性能报告（AAS、Top SQL、等待事件推断、按库/用户拆解、根因分析、优化优先级）。
本技能依赖已通过 pg-stat-snapshot 技能（或同构的快照采集机制）持续采集的历史快照数据，自身不采集快照、不修改任何数据。
前置要求
- 已安装
psql 客户端（which psql 确认）。
- 目标实例已存在快照 schema（默认
stat_snapshot），且包含至少两条覆盖分析时间段的快照记录。
- 连接凭据只能通过环境变量
PGPASSWORD 传递，禁止在命令行参数、日志或报告中明文出现密码。
- 首次执行前用
\d {schema}.* 确认实际表结构；下文 SQL 假设的表名/字段名如与实际不符，需据实调整（见"表结构假设"一节）。
输入参数（向用户确认或从对话中提取）
| 参数 | 说明 | 默认值 |
|---|
| host / port / user / dbname | 连接信息 | 无，必需 |
| PGPASSWORD | 密码，仅通过环境变量传入 | 无，必需 |
| schema | 快照所在 schema | stat_snapshot |
| start_time / end_time | 用户指定的分析时间段 | 无，必需 |
| vcpu 数量 | 用于计算 CPU 利用率，若未提供则从 pg_settings_snapshot 中查 guc 或提示用户提供 | 自动探测/询问 |
表结构假设（与 pg-stat-snapshot 对齐）
{schema}.snapshots(snapshot_id, snapshot_time, source_reset_time){schema}.pg_stat_statements_snapshot(snapshot_id, dbid, userid, queryid, query, calls, total_exec_time, rows, shared_blks_hit, shared_blks_read, blk_read_time, blk_write_time, wal_bytes){schema}.pg_stat_activity_snapshot(snapshot_id, pid, usename, application_name, datname, state, wait_event_type, wait_event, query_start){schema}.pg_stat_database_snapshot(snapshot_id, datid, datname, xact_commit, xact_rollback, blks_read, blks_hit){schema}.pg_settings_snapshot(snapshot_id, name, setting)
若实际列缺失（如 wal_bytes 在 PG13 以下不存在，blk_read_time 依赖 track_io_timing=on），对应分析项在报告中标注「当前版本/配置不支持该指标，跳过」，不要臆造数值。
工作流程
Step 1：只读会话建立
所有查询必须在只读事务中执行，使用 scripts/run_analysis.sh 统一封装：
PGPASSWORD="" psql -h -p -U -d -v ON_ERROR_STOP=1 <<
SET SESSION CHARACTERISTICS AS TRANSACTION READ ONLY;
-- 具体查询
SQL
