# Trae PostgreSQL 生产 DBA 智能体使用说明

本目录提供一个用于 Trae IDE 的 PostgreSQL 生产数据库专家智能体，以及一个专门分析 PostgreSQL 慢日志和数据库性能问题的 Skill。

适用场景：

- 生产 PostgreSQL 服务器 CPU 高占用排查。
- 慢 SQL、慢日志、`pg_stat_statements` 分析。
- 锁等待、连接数暴涨、临时文件、autovacuum、checkpoint、I/O 压力分析。
- SQL 执行计划和索引优化建议。

## 文件结构

```text
.trae/
├── agents/
│   └── postgresql-dba-agent.md
├── rules/
│   └── postgresql-production-dba.rules.md
└── skills/
    └── postgresql-log-analysis/
        ├── SKILL.md
        ├── agents/openai.yaml
        ├── references/
        │   ├── analysis-checklist.md
        │   └── postgresql-log-patterns.md
        └── scripts/
            └── parse_postgres_slowlog.py
```

## 如何在 Trae 中使用

1. 将 `.trae/` 目录放到 Trae 项目根目录。
2. 在 Trae 中创建或选择自定义 Agent。
3. 将 [agents/postgresql-dba-agent.md](agents/postgresql-dba-agent.md) 的内容作为 Agent 的系统提示词或角色说明。
4. 将 [rules/postgresql-production-dba.rules.md](rules/postgresql-production-dba.rules.md) 作为项目规则。
5. 当任务涉及 PostgreSQL 慢日志、CPU 高占用、SQL 优化或执行计划分析时，让 Agent 使用 `postgresql-log-analysis` Skill。

推荐提问方式：

```text
请使用 PostgreSQL Production DBA 智能体和 postgresql-log-analysis skill，
分析这些 PostgreSQL 慢日志，找出导致生产 CPU 高的 SQL 指纹，
并给出 safe-now、low-risk、requires-change-window 分级建议。
```

完整的分步骤提示词（慢日志 → 根因分析 → 解决方案）见 [PROMPTS.md](PROMPTS.md)。

## 分析前需要准备的材料

尽量提供同一时间窗口内的材料：

- PostgreSQL 版本。
- 事故开始和结束时间，包含时区。
- PostgreSQL 慢日志和普通数据库日志。
- CPU、load、I/O wait、内存、swap、连接数监控图。
- `pg_stat_statements` Top SQL。
- 相关 SQL 的执行计划。
- 表结构、索引定义、表大小、行数估算、autovacuum/analyze 状态。
- 最近是否有发布、迁移、批任务、流量变化或数据增长。

生产日志请先脱敏：

- 密码、token、密钥。
- 手机号、邮箱、身份证号、客户名称。
- 订单号、账户号、业务主键。
- 内网主机名、IP、连接串。

## 慢日志解析脚本

脚本位置：

```bash
.trae/skills/postgresql-log-analysis/scripts/parse_postgres_slowlog.py
```

基本用法：

```bash
python3 .trae/skills/postgresql-log-analysis/scripts/parse_postgres_slowlog.py /path/to/postgresql.log --top 30
```

输出字段：

- `calls`: 同一 SQL 指纹出现次数。
- `total_ms`: 累计耗时。
- `mean_ms`: 平均耗时。
- `max_ms`: 最大单次耗时。
- `fingerprint`: 归一化后的 SQL 指纹。

默认不会输出原始 SQL 示例，避免泄露生产敏感值。确认日志已脱敏后，可以显式开启：

```bash
python3 .trae/skills/postgresql-log-analysis/scripts/parse_postgres_slowlog.py /path/to/postgresql.log --top 30 --show-examples
```

导出 CSV：

```bash
python3 .trae/skills/postgresql-log-analysis/scripts/parse_postgres_slowlog.py /path/to/postgresql.log --csv slowlog-summary.csv
```

压缩日志先解压：

```bash
zcat postgresql.log.gz > /tmp/postgresql.log
python3 .trae/skills/postgresql-log-analysis/scripts/parse_postgres_slowlog.py /tmp/postgresql.log
```

脚本只解析文本慢日志中的 `duration: ... statement:` 或 prepared statement 的 `execute/parse/bind` 行。CSV 日志、JSON 日志、syslog、`auto_explain`、lock wait、checkpoint、autovacuum 等事件需要结合 references 中的检查清单人工分析。

## 生产安全原则

不要让 Agent 直接连接生产数据库，也不要提供生产账号密码。

`EXPLAIN ANALYZE` 不是无害操作，它会真实执行 SQL：

- 生产优先使用 replica 或 staging。
- DML 语句不要在生产执行 `EXPLAIN ANALYZE`，除非有变更窗口和回滚计划。
- 线上 SELECT 如必须执行 `EXPLAIN ANALYZE`，需要低峰窗口、`statement_timeout`、只读事务、预估返回规模和停止条件。

建议按风险分级：

- `safe-now`: 只读观察、日志分析、`pg_stat_activity`、`pg_stat_statements`、不带 `ANALYZE` 的 `EXPLAIN`。
- `low-risk`: 单条 SQL 改写、降低批大小、增加有边界的日志、对明确 stale 的表执行 `ANALYZE`。
- `requires-change-window`: 大表 `CREATE INDEX CONCURRENTLY`、DML 的 `EXPLAIN ANALYZE`、`VACUUM FULL`、非并发 `REINDEX`、全局参数调整、分区或迁移改造。

## 推荐输出格式

让智能体按下面格式输出，便于生产排障闭环：

```markdown
## 结论
一句话说明最可能原因、影响面和置信度。

## 证据
- 时间窗口：
- Top SQL 指纹：
- CPU/日志关联：
- 缺失证据：

## 主要发现
1. 问题标题
   证据：
   为什么会导致 CPU 或延迟升高：
   风险：

## 建议动作
- safe-now:
- low-risk:
- requires-change-window:

## 验证方式
- 观察指标：
- 复查 SQL 或日志：
- 回滚或停止条件：
```

## 常见命令

查看活跃会话：

```sql
SELECT pid, usename, application_name, client_addr, state,
       wait_event_type, wait_event,
       now() - xact_start AS xact_age,
       now() - query_start AS query_age,
       left(query, 500) AS query_sample
FROM pg_stat_activity
WHERE state <> 'idle'
ORDER BY query_age DESC
LIMIT 50;
```

查看 `pg_stat_statements` Top SQL：

```sql
SELECT queryid, calls, total_exec_time, mean_exec_time, max_exec_time,
       rows,
       round(rows::numeric / NULLIF(calls, 0), 2) AS rows_per_call,
       shared_blks_hit, shared_blks_read,
       temp_blks_read, temp_blks_written,
       left(query, 500) AS query_sample
FROM pg_stat_statements
ORDER BY total_exec_time DESC
LIMIT 30;
```

查看等待事件聚合：

```sql
SELECT wait_event_type, wait_event, state, count(*) AS sessions
FROM pg_stat_activity
GROUP BY wait_event_type, wait_event, state
ORDER BY sessions DESC;
```

## 交付物说明

- `postgresql-dba-agent.md`: Trae 自定义 Agent 的角色提示词。
- `postgresql-production-dba.rules.md`: 项目级生产安全和排查规则。
- `SKILL.md`: Skill 的触发说明、分析流程和输出格式。
- `analysis-checklist.md`: 生产排障证据清单和 SQL 检查语句。
- `postgresql-log-patterns.md`: 常见 PostgreSQL 日志模式解释。
- `parse_postgres_slowlog.py`: 慢 SQL 文本日志聚合脚本。