db-review
Installation
SKILL.md
数据库审查（DB Review）
数据库问题的修复成本随阶段指数增长：代码审查 < migration 审查 < 上线后排查 < 数据修复。 尽早发现，尽早修复。
第一步：确定审查范围和模式
收到审查请求
│
├─ 代码审查模式（改了数据库相关代码）
│ └─ 检查 SQL 质量 + 查询性能 + 锁风险
│
├─ Migration 审查模式（新增/修改 migration 文件）
│ └─ 检查安全性 + Schema 漂移 + 回滚方案
│
└─ 全量审查（上线前 / 用户主动要求）
└─ 代码审查 + Migration 审查 + Schema 一致性
技术栈识别
自动检测项目使用的数据库和 ORM：
| 检测目标 | 检测方式 |
|---|---|
| Prisma | prisma/schema.prisma、@prisma/client |
| TypeORM | typeorm 依赖、@Entity() 装饰器 |
| Sequelize | sequelize 依赖、.define() 调用 |
| Drizzle | drizzle-orm 依赖、drizzle.config.ts |
| SQLAlchemy | sqlalchemy 依赖、Base.metadata |
| 原生 SQL | .sql 文件、query() / execute() 调用 |
| 数据库类型 | 连接字符串、驱动依赖（pg/mysql2/better-sqlite3） |
第二步：代码审查 — SQL 质量与性能
检查维度 1：慢 SQL 模式
逐条检查以下反模式，对每个发现标注风险等级：
| 反模式 | 问题 | 正确做法 |
|---|---|---|
SELECT * |
取了不需要的列，浪费 IO 和内存 | 明确列出需要的字段 |
| 无 WHERE 的全表查询 | 数据量大时直接拖垮 DB | 加条件过滤，分页查询 |
| WHERE 中对列使用函数 | WHERE YEAR(created_at) = 2026 无法走索引 |
改为范围查询 WHERE created_at >= '2026-01-01' |
LIKE '%keyword%' |
前缀通配符无法走索引 | 考虑全文索引或搜索引擎 |
OR 条件跨列 |
优化器难以使用索引 | 拆成 UNION 或调整索引策略 |
| 子查询在 WHERE 中 | WHERE id IN (SELECT ...) 可能逐行执行 |
改为 JOIN |
ORDER BY 无索引支撑 |
大表排序触发 filesort | 确保排序字段有索引 |
DISTINCT 掩盖重复 |
通常是 JOIN 写错的信号 | 检查 JOIN 条件是否正确 |
审查方法：
- 搜索所有 SQL 语句（原生查询、ORM 的 raw query、query builder）
- 对每条 SQL 判断是否命中上述反模式
- ORM 调用也要检查——
findAll()没加条件等价于SELECT *全表扫描
检查维度 2：N+1 查询
这是 ORM 项目最常见的性能杀手。
# 反模式：循环中查询
users = User.findAll()
for user in users:
orders = Order.findAll({ where: { userId: user.id } }) # N 次查询
# 正确：预加载/JOIN
users = User.findAll({ include: [Order] }) # 1 次查询
检查方法：
- 搜索循环体内的数据库调用（
for/forEach/map中的find/query/select） - 检查 ORM 的关联查询是否使用了 eager loading（
include/joinedload/with） - 检查 GraphQL resolver 中的数据加载是否使用了 DataLoader
检查维度 3：锁表风险
以下操作在大表上可能导致长时间锁表：
| 操作 | MySQL 风险 | PostgreSQL 风险 | 安全替代 |
|---|---|---|---|
ALTER TABLE ADD COLUMN (有默认值) |
锁表重写（MySQL < 8.0） | 8.0+ 大多即时 | MySQL < 8.0 用 pt-online-schema-change |
ALTER TABLE ADD INDEX |
锁表 | 支持 CONCURRENTLY |
PG: CREATE INDEX CONCURRENTLY |
ALTER TABLE MODIFY COLUMN 改类型 |
锁表重写 | 可能锁表 | 分步迁移：新列 → 同步数据 → 切换 |
UPDATE 无 WHERE 大批量 |
行锁升级为表锁 | 大量行锁 | 分批更新（每批 1000-5000 行） |
DELETE 大批量 |
同上 | 同上 | 分批删除 + 短暂 sleep |
| 长事务中的 DDL | 锁等待、死锁 | 锁等待 | DDL 独立事务、短事务 |
审查方法：
- 检查 migration 文件中的 ALTER TABLE 操作
- 评估目标表的数据量（如果能拿到）
- 大表（>10 万行）的 DDL 操作标记为高风险
检查维度 4：索引审查
| 检查项 | 问题信号 |
|---|---|
| 缺失索引 | WHERE/JOIN/ORDER BY 中的列没有索引 |
| 冗余索引 | INDEX(a) 和 INDEX(a, b) 并存（前者被后者包含） |
| 过多索引 | 单表 >6 个索引，影响写入性能 |
| 索引列顺序 | 复合索引列顺序不符合查询模式（最左前缀原则） |
| 低选择性索引 | 在布尔/状态等低基数列上建索引（通常无效） |
| 未使用索引 | 有索引但查询没走到（函数包裹、类型不匹配） |
审查方法：
- 读取 schema/migration 中的索引定义
- 对照查询语句的 WHERE/JOIN/ORDER BY 检查索引覆盖
- ORM 的
@Index()/index: true也要检查
检查维度 5：事务与并发
| 检查项 | 关注点 |
|---|---|
| 事务范围 | 事务是否过大？包含了不必要的操作？ |
| 死锁风险 | 多个事务是否以不同顺序操作同一组表？ |
| 隔离级别 | 是否使用了过高的隔离级别（SERIALIZABLE）？ |
| 连接泄漏 | 事务/连接是否在异常路径中正确释放？ |
| 乐观锁 | 并发更新场景是否有版本号/乐观锁保护？ |
第三步：Migration 审查 — 安全性与一致性
3.1 破坏性操作检查
以下操作不可逆或有数据丢失风险，必须标记为高风险：
| 操作 | 风险 | 安全做法 |
|---|---|---|
DROP TABLE |
数据永久丢失 | 先备份、确认无引用、保留回滚窗口 |
DROP COLUMN |
列数据丢失 | 确认代码已移除引用后再删列 |
RENAME TABLE/COLUMN |
代码引用断裂 | 分步：新建 → 同步 → 切换 → 清理旧的 |
TRUNCATE |
数据清空 | 不应出现在 migration 中 |
ALTER COLUMN 收窄类型 |
数据截断 | 先检查现有数据是否溢出 |
NOT NULL 约束（已有数据列） |
空值行报错 | 先填充默认值再加约束 |
审查方法：
- 逐行读 migration 文件，标记所有 DROP/RENAME/ALTER 操作
- 每个破坏性操作必须有对应的回滚方案（down migration）
- 检查 down migration 是否真的能回滚（不是空函数）
3.2 Schema 漂移检测
这是你反复踩坑的问题：本地和服务端 schema 不一致、缺字段。
漂移来源：
1. 手动改了数据库但没写 migration（最常见）
2. migration 执行顺序不一致（分支合并后）
3. migration 只跑了一半（报错后手动修了但没记录）
4. ORM 的 model 定义和 migration 不同步
5. 多人开发时 migration 文件冲突
检查流程：
Step 1: 收集当前 Schema 定义来源
├─ ORM model/entity 定义（代码中的"应该是什么"）
├─ Migration 文件链（"变更历史"）
└─ 数据库实际状态（如果能连接）
Step 2: 交叉比对
├─ Model vs Migration：model 里的字段/类型/约束是否都有对应的 migration？
├─ Migration 完整性：migration 链是否连续？有没有遗漏？
└─ 新增字段检查：最近加的字段有 migration 吗？默认值/可空设置对吗？
Step 3: 输出不一致清单
每条记录：字段名、model 中的定义、migration 中的定义、差异描述
具体检查项：
| 检查项 | 方法 |
|---|---|
| Model 和 Migration 字段一致 | 遍历 model 所有字段，确认每个字段在 migration 链中有对应的 CREATE/ALTER |
| 类型一致 | model 中的类型（String/Int/DateTime）和 migration 中的 SQL 类型匹配 |
| 可空性一致 | model 标记 optional/nullable 的字段，migration 中没加 NOT NULL |
| 默认值一致 | model 中有 @default() 的字段，migration 中有 DEFAULT |
| 索引一致 | model 中 @index/@unique 的字段，migration 中有对应的 INDEX |
| 关联关系一致 | model 中的外键关系，migration 中有对应的 FOREIGN KEY |
| migration 时间线连续 | 按时间戳排序，检查有没有跳跃或冲突 |
3.3 回滚方案检查
每个 migration 必须有可执行的回滚方案：
| 检查项 | 要求 |
|---|---|
| down/rollback 函数存在 | 不能是空函数或 throw new Error('not implemented') |
| down 函数逻辑正确 | up 中加的列，down 中要删；up 中改的类型，down 中要改回 |
| 数据恢复 | 破坏性操作的 down 需要说明数据恢复策略（即使无法完全自动恢复） |
3.4 Migration 最佳实践
| 实践 | 要求 |
|---|---|
| 单一职责 | 一个 migration 只做一件事（加表、加列、加索引分开） |
| 可重复执行 | migration 应该幂等，重复运行不报错（IF NOT EXISTS） |
| 数据迁移分离 | schema 变更和数据填充放在不同的 migration 中 |
| 命名规范 | 文件名能反映操作内容（add_email_to_users 而非 migration_042） |
第四步：风险分级与输出
风险等级
| 等级 | 标准 | 处理要求 |
|---|---|---|
| 高危 | 数据丢失、锁表超 30s、schema 漂移（已知不一致）、无回滚方案 | 必须修复，给出具体方案 |
| 中危 | 性能隐患（N+1、缺索引）、回滚方案不完整、潜在的并发问题 | 建议修复，给出方向 |
| 低危 | 最佳实践缺失（命名、注释、冗余索引）、小表操作 | 记录，不阻断 |
输出格式
快速审查（终端输出）：
## DB Review 结果
🔴 高危 x N | 🟡 中危 x N | 🟢 低危 x N
### 高危
1. [锁表风险] migrations/20260409_add_index.sql:15 — 大表加索引未用 CONCURRENTLY
→ 修复：`CREATE INDEX CONCURRENTLY idx_users_email ON users(email);`
### 中危
1. [N+1] src/services/order.ts:42 — 循环内查询用户信息
→ 修复：使用 include/joinedload 预加载
### Schema 漂移
- ⚠️ User.phone: model 中存在(String, optional)，但无对应 migration
- ⚠️ Order.discount: model 类型 Decimal，migration 中为 Float
完整审查时，生成报告到 docs/audits/YYYY-MM-DD-db-review.md。
与其他 skill 的衔接
代码开发中
│
├─ 改了数据库代码？→ task-finish 自检时提示跑 db-review（代码审查模式）
├─ 新增 migration？→ 提交前跑 db-review（migration 审查模式）
│
↓ 上线前
├─ security-audit 审查注入防护（SQL 注入维度）
└─ db-review 全量审查（Schema 漂移 + 锁表 + 性能）
- perf-profiling：发现 DB 慢查询后，交给 db-review 做 SQL 层面的深度分析
- security-audit：SQL 注入是安全问题，由 security-audit 负责；查询性能是 db-review 负责
- task-finish：改动涉及 migration 文件时，提示跑 db-review
注意事项
- 先理解业务再审查：脱离业务的索引建议是无意义的。先搞清楚查询频率和数据量
- 小表不教条：几百行的配置表不需要纠结索引优化
- ORM 不是借口：ORM 生成的 SQL 也可能很烂，必要时看生成的实际 SQL
- 环境差异：本地 SQLite + 生产 PostgreSQL 时，migration 语法差异是漂移的常见来源
- 不替代 DBA：复杂的分库分表、主从延迟等架构级问题需要 DBA 介入
Related skills