drizzle-safe-migrations

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Drizzle Safe Migrations

Drizzle 安全迁移

Overview

概述

Use this skill to run database migrations in a way that is auditable, deployment-safe, and consistent with Drizzle's migration model.

使用本技能以可审计、部署安全且符合Drizzle迁移模型的方式运行数据库迁移。

Core Rules

核心规则

Always generate schema migrations with the project script (
```
bun run db:generate
```
).
Never hand-edit generated schema migration files.
Generate data backfills as custom migrations (
```
bun run db:generate -- --custom --name <name>
```
) and edit only that custom SQL file.
Apply data normalization before tightening constraints.
Keep one-off data fixes in migration history, not as hidden runtime logic, unless an emergency hotfix requires temporary mitigation.

始终使用项目脚本生成schema迁移（
```
bun run db:generate
```
）。
切勿手动编辑自动生成的schema迁移文件。
将数据回填生成为自定义迁移（
```
bun run db:generate -- --custom --name <name>
```
），仅编辑该自定义SQL文件。
在收紧约束前先完成数据规范化。
将一次性数据修复记录保留在迁移历史中，不要作为隐藏的运行时逻辑，除非紧急热修复需要临时处置方案。

Workflow

工作流

Classify the change:
- ```
schema-only
```
  : only column/table/index/default changes.
- ```
data+schema
```
  : old rows must be transformed before new constraints/defaults.

For

data+schema

, create custom migration first:

bun run db:generate -- --custom --name <descriptive_name>

Add idempotent backfill SQL.

Generate schema migration second:
- ```
bun run db:generate
```
Verify migration ordering in
```
drizzle/meta/_journal.json
```
:
- backfill migration index must be lower than constraint-tightening migration index.
Verify generated SQL and snapshots:
- backfill migration contains only intended data change.
- schema migration contains constraint/default/type changes.

Run full backend verification:

bun run lint && bun run typecheck && bun run test

Document deployment notes:
- expected data transformations,
- lock-risk areas,
- rollback strategy.

对变更分类：
- ```
仅schema
```
  ：仅涉及列、表、索引、默认值变更。
- ```
数据+schema
```
  ：旧行数据需要在新约束/默认值生效前完成转换。
对于
```
数据+schema
```
类型变更，先创建自定义迁移：
- ```
bun run db:generate -- --custom --name <描述性名称>
```
- 添加幂等的回填SQL语句。
再生成schema迁移：
- ```
bun run db:generate
```
在
```
drizzle/meta/_journal.json
```
中验证迁移顺序：
- 回填迁移的索引必须小于约束收紧迁移的索引。
验证生成的SQL和快照：
- 回填迁移仅包含预期的数据变更。
- schema迁移包含约束、默认值、类型变更。

运行完整的后端校验：

bun run lint && bun run typecheck && bun run test

编写部署说明文档：
- 预期的数据转换内容，
- 存在锁风险的区域，
- 回滚策略。

Backfill Requirements

回填要求

Use restrictive
```
WHERE
```
clauses.

Prefer idempotent updates (

UPDATE ... WHERE status = 'legacy_value'

Do not mix unrelated DDL/DML in the same migration.
Keep SQL explicit and minimal.

使用限制明确的
```
WHERE
```
子句。
- 优先使用幂等更新（
```
UPDATE ... WHERE status = 'legacy_value'
```
  ）。
- 不要在同一个迁移中混合不相关的DDL/DML语句。
- 保持SQL语句明确且精简。

Constraint Tightening Pattern

约束收紧模式

When removing allowed values (enum/check):

Backfill existing rows to valid target value.
Update default to new value.
Tighten check/enum constraint.

For large tables or strict uptime targets, use staged PostgreSQL patterns (

NOT VALID

VALIDATE CONSTRAINT

) where applicable.

当移除允许的取值（枚举/检查约束）时：

回填现有行数据为合法的目标值。
将默认值更新为新值。
收紧检查/枚举约束。

对于大表或者有严格可用性要求的场景，可酌情使用PostgreSQL的分阶段模式（

NOT VALID

VALIDATE CONSTRAINT

）。

Anti-Patterns

反模式

Hand-editing generated schema migration files.
Tightening constraints before backfilling existing data.
Hiding one-time migration logic in app startup code without migration artifacts.
Running migrations without validating order in the Drizzle journal.

手动编辑自动生成的schema迁移文件。
在回填现有数据前就收紧约束。
将一次性迁移逻辑隐藏在应用启动代码中，没有对应的迁移产物。
未验证Drizzle日志中的迁移顺序就运行迁移。

Reference

参考资料

See
```
references/production-playbook.md
```
for command templates and review checklists.

查看
```
references/production-playbook.md
```
获取命令模板和审核检查清单。