The Expand-Contract Pattern
You'll learn how to evolve database schemas without breaking production systems using a three-phase approach.
When you need to change your database schema in a live system, you can't just flip a switch—existing code and queries may break instantly. The Expand-Contract Pattern (also called Parallel Change) gives you a safe, gradual path forward.
How It Works
The pattern has three distinct phases:
1. Expand
Add the new schema element (column, table, or structure) alongside the old one. Don't remove anything yet. Both old and new coexist.
For example, if you're renaming email to email_address:
- Add the new
email_addresscolumn - Keep the old
emailcolumn intact - Start writing to both columns in your application code
2. Migrate
Gradually transition your system to use the new schema:
- Backfill historical data from old to new
- Update application code to read from the new column
- Deploy changes incrementally
- Verify everything works correctly
During this phase, you might write to both but read from the new one.
3. Contract
Once all code paths use the new schema and you've verified correctness:
- Remove application code that references the old schema
- Drop the old database column/table
The Safety Net
This pattern provides rollback safety—if something breaks during migration, you can revert code changes because the old schema still exists. You're never in a state where the database and code are fundamentally incompatible.
Key Takeaway: The Expand-Contract Pattern makes schema changes safe by temporarily supporting both old and new structures, allowing gradual migration without downtime or breaking changes.