数据库迁移模式¶

用于生产环境系统的安全且可逆的数据库模式变更。

激活时机¶

• 创建或修改数据库表
• 添加/删除列或索引
• 执行数据迁移（回填、转换）
• 计划零停机模式变更
• 为新项目配置迁移工具

核心原则¶

1. 所有变更都是迁移 — 不要手动修改生产环境数据库
2. 迁移在生产环境中只向前执行 — 回滚使用新的前向迁移
3. 模式迁移和数据迁移分离 — 不要在一个迁移中混合 DDL 和 DML
4. 针对生产环境规模的数据测试迁移 — 在 100 行上能正常工作的迁移在 1000 万行上可能会锁表
5. 迁移部署后不可变 — 不要编辑已在生产环境执行的迁移

迁移安全检查清单¶

在应用迁移之前：

• [ ] 迁移同时具有 UP 和 DOWN（或明确标记为不可逆）
• [ ] 大型表没有完整表锁（使用并发操作）
• [ ] 新列具有默认值或可空（不要添加无默认值的 NOT NULL）
• [ ] 索引并发创建（不要在现有表的 CREATE TABLE 中内联创建）
• [ ] 数据回填是与模式变更分离的迁移
• [ ] 针对生产环境数据副本进行测试
• [ ] 文档化回滚计划

PostgreSQL 模式¶

安全添加列¶

-- GOOD: Nullable列、ロックなし
ALTER TABLE users ADD COLUMN avatar_url TEXT;

-- GOOD: デフォルト付きの列（Postgres 11+は即座、書き直しなし）
ALTER TABLE users ADD COLUMN is_active BOOLEAN NOT NULL DEFAULT true;

-- BAD: 既存テーブルのデフォルトなしで NOT NULL（完全書き直し必須）
ALTER TABLE users ADD COLUMN is_active BOOLEAN NOT NULL;

有关详细信息，请参阅文档。