pg-perf-insight

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