process-db-report

数据库性能报告处理

分析数据库可观测性报告，并为 Drizzle ORM 代码库制定按优先级排序的优化计划。

分诊工作流

1. 解析报告 — 从粘贴的可观测性报告中提取结构化数据。
2. 验证报告完整性 — 在提出建议前，找出缺失的部分。
3. 分析问题 — 使用基于证据的规则检测影响较大的问题。
4. 确定优先级 — 按影响程度（高／中／低）排列问题。
5. 生成行动计划 — 提出具体、安全的任务，并提供架构层面的指导。

不完整报告的处理方式

• 缺少必要数据时，先询问缺失的部分，不要猜测。
• 仅请求针对受阻建议所需的缺失部分。
• 有部分数据时，将建议标记为有条件。

完整分诊所需的部分：

• 表统计信息
• 高频顺序扫描
• 未使用／很少使用的索引
• 缺少索引的外键
• 缓存命中率

---

问题检测启发式规则

严重问题（立即处理）

问题	检测规则	操作
表膨胀	表统计信息中的死行数 >10%	通过 /app/admin/observability UI 执行 VACUUM
索引覆盖不足／缺失	索引使用率 <50%，且顺序扫描频繁，并且已知查询存在筛选／排序模式	仅在验证查询模式后，才在 packages/db/src/schema.ts 中提出索引策略
缺少索引的外键	外键列没有对应索引	在 schema.ts 中添加索引

中优先级（下个迭代）

问题	检测规则	操作
未使用的索引	在指定的工作负载时间段内，非唯一索引的使用率较低	仅在验证实际查询路径并完成安全检查后，才从 schema.ts 中移除
重复索引	多个索引覆盖相同列	移除冗余索引

低优先级（监控）

问题	检测规则	操作
缓存命中率	低于 99%	先调查工作负载和缓存行为；将 shared_buffers 调优作为可选的基础设施级后续措施

---

预期报告格式

Table Statistics:
| table_name | total_size | dead_rows | dead_ratio_pct |
|------------|------------|-----------|----------------|
| users      | 2048 MB    | 15000     | 12.5           |

High Sequential Scans:
| table_name | sequential_scans | index_usage_pct |
|------------|------------------|-----------------|
| sessions   | 45000            | 25              |

Unused/Rarely Used Indexes:
| index_name           | times_used | index_size |
|---------------------|------------|------------|
| idx_old_feature     | 2          | 5 MB       |

Foreign Keys Without Indexes:
| table_name | column_name | suggested_index |
|------------|-------------|-----------------|
| posts      | user_id     | CREATE INDEX... |

Cache Hit Ratio:
| cache_hit_ratio_pct |
|---------------------|
| 97.5                |

---

索引安全规则

绝不删除以下索引：

• 主键（*_pkey）
• 唯一约束（*_unique）
• 业务逻辑约束（例如，organizations_slug_unique）

可以安全删除：

• 在具有代表性的工作负载时间窗口内（例如，根据流量模式选择 7-30 天），使用率始终较低的非唯一索引
• 冗余索引（已被复合索引覆盖）

删除前检查（必需）：

• 在判定某个索引未被使用之前，验证工作负载时间窗口的覆盖情况。
• 在删除之前，从真实应用路径（API 端点、后台任务、cron 流程）验证查询路径的使用情况。
• 确认不存在通过约束、迁移或运维工作流产生的隐藏依赖。
• 如果缺少查询路径验证数据，建议应附带条件。

安全删除示例：

// oauth_consents has composite unique(userId, clientId)
// So single-column index on clientId alone is redundant
index("oauth_consents_client_id_idx"); // SAFE TO REMOVE

---

行动计划模板

加载并遵循 references/action-plan-template.md，以获取完整的输出结构和措辞。

---

重要规则

• 引用实际文件路径（packages/db/src/schema.ts）
• 为 schema 变更提供精确的代码片段
• 按影响程度排序（无效行 > 缺失索引 > 未使用索引）
• 绝不建议临时编写 SQL——schema.ts 是唯一事实来源
• 在末尾包含工作流步骤
• 仅当报告提供了足够数据、能够支持可信估算时，才估算改进幅度
• 将 shared_buffers 调优视为可选的基础设施指导，仅在需要升级处理时提供

---

相关技能

• performance-optimization — Effect 并行模式、N+1 修复、批量操作
• drizzle-database — Schema 模式、迁移、关联关系
• production-troubleshooting — Kubernetes 性能调试