Expand-Contract Migration

Overview

Expand-contract, also called parallel change, makes incompatible changes compatible by never doing the breaking part and the dependent part together. Think of it as building a second bridge before demolishing the first.

How it works

Take renaming the column fullname to display_name.

1 EXPAND    add column display_name (nullable)
2 WRITE     app writes both columns
3 BACKFILL  copy fullname into display_name in batches
4 READ      app reads display_name
5 CONTRACT  stop writing fullname, then drop column

Each numbered step is its own deploy. After step 2, a rollback to the earlier app version is safe because the old column is still maintained. After step 4, rollback to the previous release still works because both columns hold data.

ALTER TABLE users ADD COLUMN display_name text;

The same shape applies to APIs: add the new field, support both, migrate clients, then remove the old one after usage drops to zero.

Pitfalls

• Skipping the verification between read-switch and contract. Measure that the old column is unused first.
• Backfilling in one giant transaction that locks the table. Batch with throttling.
• Adding NOT NULL or defaults in a way that rewrites a large table.
• Forgetting to remove dual-write code, leaving permanent clutter.
• Contracting while an old mobile app version is still in the field.

Key takeaways

• Never ship a breaking change and its dependents together.
• Expand, migrate, then contract, each as a separate release.
• Keep rollback possible at every step.
• Backfill in throttled batches.
• Track the contract step so it actually happens.