rails-migration-safety

Rails 迁移安全

当架构变更必须在真实环境中安全执行时，请使用此技能。

核心原则： 对大型或繁忙的表，优先采用分阶段发布，而不是一次性迁移。

快速参考

操作	安全模式
添加列	先设为可空，之后回填，最后强制 NOT NULL
添加索引（大型表）	algorithm: :concurrent（PG）/ :inplace（MySQL）
回填数据	使用批处理任务，不要放在迁移事务中
重命名列	添加新列、复制数据、迁移调用方、删除旧列
添加 NOT NULL	确认所有行都有值后再添加
添加外键	清理孤立记录后再添加
删除列	先移除代码引用，再删除列

硬性门槛

DO NOT combine schema change and data backfill in one migration.
DO NOT add NOT NULL on a column that hasn't been fully backfilled.
DO NOT drop columns before all code references are removed.

审查顺序

1. 确认数据库和表大小带来的风险。
2. 将架构变更与数据回填分开。
3. 检查索引、约束、默认值和重写的锁行为。
4. 规划应用代码与迁移代码的部署顺序。
5. 规划回滚或向前修复策略。

安全模式

• 先添加可空列，之后回填，最后强制 NOT NULL。
• 在支持的情况下并发添加索引。
• 数据量较大时，在长事务之外分批回填。
• 在过渡期间，部署能够兼容新旧架构的代码。
• 对重命名、类型变更和唯一约束采用多步发布。

如果项目使用 strong_migrations，请遵循其规则。如果没有使用，也要手动应用相同的安全规则。

示例

有风险（避免）：

add_column :orders, :status, :string, default: 'pending', null: false
Order.update_all("status = 'pending'")

• 风险： 长时间锁定；在大型表上应用默认值会重写表。

安全模式：

# Step 1: add nullable column
add_column :orders, :status, :string

# Step 2 (separate deploy): backfill in batches outside migration

# Step 3 (after backfill): add constraint
change_column_null :orders, :status, false
change_column_default :orders, :status, from: nil, to: 'pending'

大型表上的索引：

# PostgreSQL: concurrent index (no write lock)
disable_ddl_transaction!
add_index :orders, :processed_at, algorithm: :concurrent

# MySQL: online DDL
add_index :orders, :processed_at, algorithm: :inplace

常见错误

错误	实际情况
“表很小，不需要分阶段迁移”	表会增长。应养成对所有迁移都分阶段处理的习惯。
在一次迁移中同时变更架构并回填数据	长事务、长时间锁定。务必分开处理。
重命名列后立即切换应用	部署期间应用会崩溃。应使用添加、复制、迁移、删除的流程。
使用 add_index 时不指定 algorithm: :concurrent	大型 PostgreSQL 表上的排他锁会阻止写入。
回填完成前添加 NOT NULL	迁移会失败，或在等待回填期间锁定表。
移除代码引用前删除列	访问缺失列时应用会崩溃。

危险信号

• 在一次长时间迁移中同时进行架构变更和数据回填
• 重命名列时，应用代码假定会立即切换
• 对大型表设置默认值、重写数据或变更 NOT NULL，却没有分阶段计划
• 清理现有数据前添加外键或唯一约束
• 在替代路径的同一次部署中执行破坏性移除或删除
• 未记录回滚或向前修复策略

输出风格

先列出风险。

每项风险都应包含：

• 迁移步骤
• 可能的失败模式或锁风险
• 更安全的发布方式
• 回滚或向前修复说明

有关复杂类型变更、多步唯一约束、延迟验证外键、安全删除列和多数据库迁移，请参阅 PATTERNS.md。

集成

技能	何时串联使用
rails-code-review	审查包含迁移的 PR 时
rails-background-jobs	架构变更后运行回填任务时
rails-security-review	迁移会暴露或转移敏感数据时