Rails Migration Safety
Use this skill when schema changes must be safe in real environments.
Core principle: Prefer phased rollouts over one-shot migrations on large or busy tables.
Quick Reference
| Operation |
Safe Pattern |
| Add column |
Nullable first, backfill later, enforce NOT NULL last |
| Add index (large table) |
algorithm: :concurrent (PG) / :inplace (MySQL) |
| Backfill data |
Batch job, not inside migration transaction |
| Rename column |
Add new, copy data, migrate callers, drop old |
| Add NOT NULL |
After backfill confirms all rows have values |
| Add foreign key |
After cleaning orphaned records |
| Remove column |
Remove code references first, then drop column |
HARD-GATE
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.
Review Order
- Identify the database and table-size risk.
- Separate schema changes from data backfills.
- Check lock behavior for indexes, constraints, defaults, and rewrites.
- Plan deployment order between app code and migration code.
- Plan rollback or forward-fix strategy.
Safe Patterns
- Add nullable column first, backfill later, enforce
NOT NULL last.
- Add indexes concurrently when supported.
- Backfill in batches outside a long transaction when volume is high.
- Deploy code that tolerates both old and new schemas during transitions.
- Use multi-step rollouts for renames, type changes, and unique constraints.
If the project uses strong_migrations, follow it. If it does not, apply the same safety rules manually.
Examples
Risky (avoid):
add_column :orders, :status, :string, default: 'pending', null: false
Order.update_all("status = 'pending'")
- Risk: Long lock; table rewrite if default is applied on large table.
Safe pattern:
# 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'
Index on large tables:
# 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
Common Mistakes
| Mistake |
Reality |
| "Table is small, no need for phased migration" |
Tables grow. Build the habit for all migrations. |
| Schema change + backfill in one migration |
Long transaction, long lock. Always separate them. |
| Column rename with immediate app cutover |
App will crash during deploy. Use add-copy-migrate-drop. |
add_index without algorithm: :concurrent |
Exclusive lock on large PostgreSQL tables blocks writes. |
| Adding NOT NULL before backfill completes |
Migration fails or locks table waiting for backfill. |
| Removing column before removing code references |
App crashes when accessing the missing column. |
Red Flags
- Schema change and data backfill combined in one long migration
- Column rename with app code assuming immediate cutover
- Large-table default, rewrite, or NOT NULL change without a phased plan
- Foreign key or unique constraint added before cleaning existing data
- Destructive remove or drop in the same deploy as the replacement path
- No rollback or forward-fix strategy documented
Output Style
List risks first.
For each risk include:
- Migration step
- Likely failure mode or lock risk
- Safer rollout
- Rollback or forward-fix note
For complex type changes, multi-step unique constraints, foreign key validation deferral, safe column removal, and multi-database migrations see PATTERNS.md.
Integration
| Skill |
When to chain |
| rails-code-review |
When reviewing PRs that include migrations |
| rails-background-jobs |
For backfill jobs that run after schema change |
| rails-security-review |
When migrations expose or move sensitive data |
1---2name: rails-migration-safety3description: Use when planning or reviewing production database migrations, adding columns, indexes, constraints, backfills, renames, table rewrites, or concurrent operations. Covers phased rollouts, lock behavior, rollback strategy, strong_migrations compliance, and deployment ordering for schema changes.4license: MIT5---6
7# Rails Migration Safety
8
9Use this skill when schema changes must be safe in real environments.
10
11**Core principle:** Prefer phased rollouts over one-shot migrations on large or busy tables.
12
13## Quick Reference
14
15| Operation | Safe Pattern |
16|-----------|-------------|
17| Add column | Nullable first, backfill later, enforce NOT NULL last |
18| Add index (large table) | `algorithm: :concurrent` (PG) / `:inplace` (MySQL) |
19| Backfill data | Batch job, not inside migration transaction |
20| Rename column | Add new, copy data, migrate callers, drop old |
21| Add NOT NULL | After backfill confirms all rows have values |
22| Add foreign key | After cleaning orphaned records |
23| Remove column | Remove code references first, then drop column |
24
25## HARD-GATE
26
27```
28DO NOT combine schema change and data backfill in one migration.
29DO NOT add NOT NULL on a column that hasn't been fully backfilled.
30DO NOT drop columns before all code references are removed.
31```
32
33## Review Order
34
351. Identify the database and table-size risk.
362. Separate schema changes from data backfills.
373. Check lock behavior for indexes, constraints, defaults, and rewrites.
384. Plan deployment order between app code and migration code.
395. Plan rollback or forward-fix strategy.
40
41## Safe Patterns
42
43- Add nullable column first, backfill later, enforce `NOT NULL` last.
44- Add indexes concurrently when supported.
45- Backfill in batches outside a long transaction when volume is high.
46- Deploy code that tolerates both old and new schemas during transitions.
47- Use multi-step rollouts for renames, type changes, and unique constraints.
48
49If the project uses `strong_migrations`, follow it. If it does not, apply the same safety rules manually.
50
51## Examples
52
53**Risky (avoid):**
54
55```ruby
56add_column :orders, :status, :string, default: 'pending', null: false
57Order.update_all("status = 'pending'")
58```
59
60- **Risk:** Long lock; table rewrite if default is applied on large table.
61
62**Safe pattern:**
63
64```ruby
65# Step 1: add nullable column
66add_column :orders, :status, :string
67
68# Step 2 (separate deploy): backfill in batches outside migration
69
70# Step 3 (after backfill): add constraint
71change_column_null :orders, :status, false
72change_column_default :orders, :status, from: nil, to: 'pending'
73```
74
75**Index on large tables:**
76
77```ruby
78# PostgreSQL: concurrent index (no write lock)
79disable_ddl_transaction!
80add_index :orders, :processed_at, algorithm: :concurrent
81
82# MySQL: online DDL
83add_index :orders, :processed_at, algorithm: :inplace
84```
85
86## Common Mistakes
87
88| Mistake | Reality |
89|---------|---------|
90| "Table is small, no need for phased migration" | Tables grow. Build the habit for all migrations. |
91| Schema change + backfill in one migration | Long transaction, long lock. Always separate them. |
92| Column rename with immediate app cutover | App will crash during deploy. Use add-copy-migrate-drop. |
93| `add_index` without `algorithm: :concurrent` | Exclusive lock on large PostgreSQL tables blocks writes. |
94| Adding NOT NULL before backfill completes | Migration fails or locks table waiting for backfill. |
95| Removing column before removing code references | App crashes when accessing the missing column. |
96
97## Red Flags
98
99- Schema change and data backfill combined in one long migration
100- Column rename with app code assuming immediate cutover
101- Large-table default, rewrite, or NOT NULL change without a phased plan
102- Foreign key or unique constraint added before cleaning existing data
103- Destructive remove or drop in the same deploy as the replacement path
104- No rollback or forward-fix strategy documented
105
106## Output Style
107
108List risks first.
109
110For each risk include:
111- Migration step
112- Likely failure mode or lock risk
113- Safer rollout
114- Rollback or forward-fix note
115
116For complex type changes, multi-step unique constraints, foreign key validation deferral, safe column removal, and multi-database migrations see [PATTERNS.md](./PATTERNS.md).
117
118## Integration
119
120| Skill | When to chain |
121|-------|---------------|
122| **rails-code-review** | When reviewing PRs that include migrations |
123| **rails-background-jobs** | For backfill jobs that run after schema change |
124| **rails-security-review** | When migrations expose or move sensitive data |
aibot88