review-migration

用途

review-migration 用于在规划或审查生产环境 Rails 数据库迁移时，确保 schema 变更在真实环境中安全执行。它适用于需要评估迁移风险、避免锁表或数据不一致的场景。

主要能力

该技能提供一套硬性规则（HARD-GATE）：

不得在同一个迁移中混合 schema 变更与数据回填。
不得对尚未完全回填的列添加 NOT NULL。
不得在代码引用全部移除前删除列。

核心流程包括：

识别数据库与表规模风险。
将 schema 变更与数据回填分离。
检查索引、约束、默认值和表重写的锁行为。
规划应用代码与迁移代码之间的部署顺序。
规划回滚或前向修复策略。
若项目使用 strong_migrations，则遵循它；若未使用，则手动应用同等安全规则。

技能还提供安全模式与常见错误对照表，覆盖以下操作：添加列、添加索引（大表）、回填数据、重命名列、添加 NOT NULL、添加外键、删除列。每一步都要求明确说明预期的锁或表重写风险；若风险可忽略，需说明原因。同时要求在过渡期间部署能同时兼容新旧 schema 的代码。

使用方式

该技能以规则和流程形式使用，审查或规划迁移时逐项对照。技能包含代码示例：

并发索引（Rails / PostgreSQL）：

class AddIndexOnUsersEmail < ActiveRecord::Migration[7.1]
  disable_ddl_transaction!

  def change
    add_index :users, :email, algorithm: :concurrently
  end
end

disable_ddl_transaction! 是必需的——并发索引创建不能在事务内运行。

可空优先加延迟 NOT NULL（Rails）：

# Step 1 — Deploy: add nullable column
class AddConfirmedAtToUsers < ActiveRecord::Migration[7.1]
  def change
    add_column :users, :confirmed_at, :datetime
  end
end

# Step 2 — Backfill outside migration (background job or script)
User.in_batches(of: 1_000) do |batch|
  batch.update_all(confirmed_at: Time.current)
  sleep(0.05) # throttle to reduce replication lag
end

# Step 3 — Deploy: enforce NOT NULL only after all rows are filled
class ChangeConfirmedAtNotNull < ActiveRecord::Migration[7.1]
  def change
    change_column_null :users, :confirmed_at, false
  end
end

类型变更发布（5 步）：

添加新的类型列，设为可空。
应用代码同时写入旧列和新列。
在迁移事务之外分批回填。
一致性检查通过后从新列读取。
停止写入旧列，在后续部署中删除它。

输出风格要求：先列风险；每项风险包含迁移步骤、可能失败模式、显式锁/表重写风险、更安全的发布方式、回滚或前向修复说明；确保包含向后兼容步骤；始终为列重命名、类型变更和唯一约束提供显式分阶段模式，若不适用则标记为 Not applicable 并解释原因。语言要求为英文，除非明确要求其他语言。

适用场景

规划生产环境 Rails 数据库迁移。
审查包含迁移的 PR。
需要评估锁表、表重写或数据回填风险时。
需要制定回滚或前向修复策略时。

限制

该技能针对 Rails 迁移，主要示例为 PostgreSQL 和 MySQL。具体数据库版本差异（如 PG < 11 的表重写行为）需结合实际情况判断。技能本身不执行迁移，仅提供规则、流程和示例。

集成

该技能可与其他技能链式配合：

code-review：审查包含迁移的 PR 时。
implement-background-job：用于 schema 变更后运行的回填任务。
security-check：当迁移暴露或移动敏感数据时。

技能介绍

用途

主要能力

使用方式

适用场景

限制

集成