---
name: db-review
version: 1.0.0
last_updated: 2026-04-09
repository: https://github.com/312362115/claude
description: >
  数据库代码审查 + Migration 安全检查。
  代码审查：锁表风险、索引缺失、慢 SQL 模式、N+1 查询。
  Migration 审查：破坏性操作、Schema 漂移检测、回滚方案。
  适用于 SQL（MySQL/PostgreSQL/SQLite）和 ORM（Prisma/TypeORM/Sequelize/SQLAlchemy/Drizzle）。
  触发词：数据库检查、migration 检查、慢 SQL、索引、锁表、schema 漂移、db review。
  触发场景：新增/修改 migration 文件后、数据库相关代码 review、上线前检查、性能排查中发现 DB 瓶颈。
---

# 数据库审查（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 条件是否正确 |

**审查方法**：
1. 搜索所有 SQL 语句（原生查询、ORM 的 raw query、query builder）
2. 对每条 SQL 判断是否命中上述反模式
3. 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 次查询
```

**检查方法**：
1. 搜索循环体内的数据库调用（`for`/`forEach`/`map` 中的 `find`/`query`/`select`）
2. 检查 ORM 的关联查询是否使用了 eager loading（`include`/`joinedload`/`with`）
3. 检查 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 独立事务、短事务 |

**审查方法**：
1. 检查 migration 文件中的 ALTER TABLE 操作
2. 评估目标表的数据量（如果能拿到）
3. 大表（>10 万行）的 DDL 操作标记为**高风险**

### 检查维度 4：索引审查

| 检查项 | 问题信号 |
|--------|---------|
| 缺失索引 | WHERE/JOIN/ORDER BY 中的列没有索引 |
| 冗余索引 | `INDEX(a)` 和 `INDEX(a, b)` 并存（前者被后者包含） |
| 过多索引 | 单表 >6 个索引，影响写入性能 |
| 索引列顺序 | 复合索引列顺序不符合查询模式（最左前缀原则） |
| 低选择性索引 | 在布尔/状态等低基数列上建索引（通常无效） |
| 未使用索引 | 有索引但查询没走到（函数包裹、类型不匹配） |

**审查方法**：
1. 读取 schema/migration 中的索引定义
2. 对照查询语句的 WHERE/JOIN/ORDER BY 检查索引覆盖
3. ORM 的 `@Index()`/`index: true` 也要检查

### 检查维度 5：事务与并发

| 检查项 | 关注点 |
|--------|--------|
| 事务范围 | 事务是否过大？包含了不必要的操作？ |
| 死锁风险 | 多个事务是否以不同顺序操作同一组表？ |
| 隔离级别 | 是否使用了过高的隔离级别（SERIALIZABLE）？ |
| 连接泄漏 | 事务/连接是否在异常路径中正确释放？ |
| 乐观锁 | 并发更新场景是否有版本号/乐观锁保护？ |

---

## 第三步：Migration 审查 — 安全性与一致性

### 3.1 破坏性操作检查

**以下操作不可逆或有数据丢失风险**，必须标记为高风险：

| 操作 | 风险 | 安全做法 |
|------|------|---------|
| `DROP TABLE` | 数据永久丢失 | 先备份、确认无引用、保留回滚窗口 |
| `DROP COLUMN` | 列数据丢失 | 确认代码已移除引用后再删列 |
| `RENAME TABLE/COLUMN` | 代码引用断裂 | 分步：新建 → 同步 → 切换 → 清理旧的 |
| `TRUNCATE` | 数据清空 | 不应出现在 migration 中 |
| `ALTER COLUMN` 收窄类型 | 数据截断 | 先检查现有数据是否溢出 |
| `NOT NULL` 约束（已有数据列） | 空值行报错 | 先填充默认值再加约束 |

**审查方法**：
1. 逐行读 migration 文件，标记所有 DROP/RENAME/ALTER 操作
2. 每个破坏性操作必须有对应的**回滚方案**（down migration）
3. 检查 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 介入