Expand and contract changes a database schema without downtime in three phases: add the new structure alongside the old, migrate code and data while both coexist, then remove the old structure once nothing reads it. Each phase stays backward compatible, so the application keeps running. It trades extra steps and temporary duplication for a rollback point at every stage.
Key takeaways
- Expand and contract replaces one risky change with several small, reversible ones.
- Locks taken by a direct schema change can block traffic, so the first goal is to avoid long exclusive locks.
- Old and new structures must coexist until every reader and writer has moved to the new one.
- The contract phase should run only after you have verified that nothing still depends on the old structure.
What is expand and contract?
Expand and contract is a way of changing a schema in stages so that the application never depends on a structure that is being removed. It is a specific form of what Martin Fowler calls parallel change, described in his article on parallel change.
The pattern has three phases. In the expand phase you add the new table, column or index while the old one still exists. In the migrate phase you move reads and writes and backfill existing rows. In the contract phase you remove the old structure once nothing uses it.
Each phase must leave the system compatible with the code running immediately before it. That is what makes rollback possible: if something breaks, you revert the code, not the data.
The method is most useful when a system cannot stop for a change. Order processing, bookings and partner-facing integration endpoints are typical cases, because a short outage there affects customers and partners directly, not only internal staff.
Why does a direct schema change cause downtime?
A direct change usually causes downtime because of locking, not because the change is conceptually complicated. Many DDL statements take a lock that blocks reads, writes or both while they run. In PostgreSQL, for example, ALTER TABLE acquires an ACCESS EXCLUSIVE lock for many forms of change, as described in the PostgreSQL ALTER TABLE documentation.
Lock duration depends on the engine, the statement and the size of the table, and behaviour can change between versions. Check the documentation for the version you run before assuming that a change is online.
Downtime also comes from the deploy gap. Code and schema rarely switch over at the same instant, so for a short window old code meets the new schema or the reverse. A direct rename or drop breaks one side of that window.
How do you change a database schema without downtime in the expand phase?
The expand phase is safe when every addition is backward compatible. The old code should never notice the change. New columns should be nullable or have a default the old code does not need to know about, and new tables should not alter anything existing code reads.
Expand checklist
- Add new columns as nullable, and avoid defaults that force a full table rewrite on large tables.
- Create indexes concurrently where the engine supports it.
- Deploy application code that tolerates both the old and the new shape.
- Verify the migration in staging with a copy of production-like data volume.
Keep schema changes and data backfills in separate migration files. Separate files can be retried, paused and reviewed on their own, which matters when a backfill runs for hours.
Teams that automate migrations inside their delivery pipeline should review the approach alongside their release process. Our cloud and DevOps services page describes how deployment pipelines are set up for this kind of work.
How do you move reads and writes across?
Move reads first, then writes, and backfill history in small batches. Reading from the new structure only after the backfill has been verified keeps the switch reversible.
Switching reads with a flag
Put the read path behind a feature flag so you can return to the old structure without a deploy. Scope the flag per service or per tenant, so a problem affects a slice of traffic rather than all of it.
Backfilling in batches
Copy rows in bounded chunks keyed on the primary key, committing between chunks. Long single transactions hold locks and grow logs; short batches let you pause and resume without losing progress.
Dual writes
During migration the application may write to both structures. This is the riskiest part: if the two writes are not in one transaction, they can diverge. Compare row counts and checksums on samples, and decide in advance which side wins when they disagree.
When is it safe to remove the old structure?
It is safe to remove the old structure only after no code path reads or writes it across a full cycle of normal traffic. That usually means days of monitoring after the last deploy, not minutes.
Removing the old structure in order
Stop writes to the old structure first, then stop reads, then drop it in a separate release. Confirm with query logs or metrics that the old column is no longer touched. Keep an export of the dropped data for as long as your recovery policy requires.
How does expand and contract compare with other approaches?
Expand and contract trades speed and simplicity for safety. The table compares it qualitatively with two common alternatives.
| Criterion | Direct change in a maintenance window | Expand and contract | Online schema change tool |
|---|---|---|---|
| Downtime risk | High unless the window is planned well | Low when each phase stays compatible | Low to moderate, depending on the tool and the change |
| Number of deploys | One | Several | One, plus tool setup |
| Rollback | Often hard after data has changed | Possible at each phase | Depends on how the tool cuts over |
| Operational effort | Low on paper, high under pressure | Higher, and needs discipline | Higher, and needs tool expertise |
Hypothetical examples of expand and contract
Here are two hypothetical scenarios:
Renaming a column
A team wants to rename a customer reference column. In the expand phase they add the new column and write to both. They backfill history in batches, switch reads behind a flag, and drop the old column in a later release once monitoring shows no reads.
Splitting a table
A team moves address fields out of a customer table into a new table. Reads switch first, with a fallback to the old columns during the migrate phase, so a missing row does not produce an error for the user. The old columns are removed only after the reconciliation job reports no differences.
Where does expand and contract fail?
It fails when teams skip verification during the migrate phase or drop the old structure too early. It also struggles with changes that cannot be made compatible, such as a type change that alters the stored meaning of a value.
- Dual writes without a single transaction can silently diverge.
- Reporting jobs and external integrations that read the old column are easy to forget.
- Long-running backfills can compete with peak traffic for resources.
Teams that connect several systems often find that the hidden readers live in other services. Mapping every consumer, including reports and partner integrations, before the contract phase prevents most surprises. If your schema spans several systems, our system integration work covers how these dependencies are mapped and tested.
Frequently Asked Questions
Does expand and contract always avoid downtime?
No single method guarantees zero downtime. Expand and contract avoids downtime when each phase stays compatible with the code running at the time and when DDL statements do not block traffic for long. It still needs careful lock management, verified backfills and monitoring before the contract phase, because a missed reader can fail after the drop.
How long should the migrate phase last?
The migrate phase lasts until the backfill is verified and all reads use the new structure, so there is no fixed duration. Teams usually keep it running long enough to observe a full business cycle, including batch jobs and reports, before moving on.
Can I use expand and contract with any database?
Most relational databases support the pattern because it relies on ordinary schema changes and application code. Whether individual statements are online depends on the engine and its version, so check the documentation for each change type before you rely on it.
Should dual writes run in one transaction?
Yes, whenever both structures live in the same database and the engine allows it. A single transaction keeps them consistent. If the writes must span services, use an outbox pattern or a reconciliation job, and accept that consistency will be eventual.
When should a team bring in outside help?
A team should consider outside help when a migration touches many services or customer-facing systems and internal staff have little time to plan it. Rui Codex offers technical implementation support for this kind of work, and you can request a project consultation at https://ruicodex.com/Contact.
Conclusion
Expand and contract is a disciplined way to change a live schema: make additions compatible, move traffic in reversible steps, and remove the old structure only after evidence that nothing depends on it. The main costs are extra deploys, temporary duplication and the care needed during dual writes. The right sequence depends on your engine, your traffic pattern and your consumers, so write those down before the first migration file. To plan a migration, request a project consultation at the Rui Codex contact page or email info@ruicodex.com. Published examples of delivered work are on the case studies page.
Sources
- Parallel Change - Martin Fowler
- ALTER TABLE - PostgreSQL Global Development Group