Moving Tenants to the New Wing: The Expand-Contract Migration Pattern

Opening Scene

A careful building manager renovating an occupied structure doesn’t demolish the old wing and then start building the new one. They build the new wing first, move tenants over once it’s ready and proven livable, and only then demolish the old wing everyone has already vacated. Reversing that order — demolish first, build second — would leave tenants with nowhere to live in between.

The expand-contract pattern applies this exact same careful sequencing to a schema migration.

In Plain English

The expand-contract pattern breaks a genuinely breaking schema change into three safer phases: expand (add the new structure alongside the old, both coexisting), migrate (move consumers and data over to the new structure while the old one still works as a fallback), and contract (remove the old structure only once every consumer has genuinely finished migrating). This sequencing avoids ever requiring an instantaneous, all-or-nothing cutover.

The Old Way

Before the expand-contract pattern became a widely adopted discipline, breaking schema changes were often attempted with much riskier, single-step approaches:

A breaking change was sometimes deployed as a single, all-at-once cutover, similar to demolishing the old wing before the new one was ready, leaving no safe fallback if anything went wrong.
Rolling back a failed single-step migration was often difficult or impossible once the old structure was already gone, similar to tenants having nowhere to go once their old wing has already been torn down.
Coordinating every consumer to migrate at the exact same moment a single-step cutover required was rarely realistic, given the compatibility challenges covered in Article 14.

This risky, single-step approach is precisely what the expand-contract pattern was built to replace.

What’s Changing (and Why AI Is the Reason)

AI-assisted migration planning can now automatically generate an expand-contract sequence for a proposed breaking change, identifying the specific expand and contract steps needed and the safe order to execute them, rather than requiring a human to manually design this sequencing from scratch every time. This directly operationalizes the breaking-change identification from Article 12 into a concrete, safe execution plan.
AI-assisted migration progress tracking can monitor, in real time, how many consumers have actually completed their migration to the new structure during the migrate phase, letting a team know precisely when it’s genuinely safe to proceed to the contract phase, rather than guessing or committing to a fixed, arbitrary timeline. This directly extends the rollout coordination introduced in Article 14, applied specifically to expand-contract migrations.
AI-assisted rollback readiness checking can verify, throughout the expand and migrate phases, that the old structure remains genuinely functional as a fallback, catching a case where the “safe” old path has quietly broken and would no longer actually work if a rollback were needed. This closes a real risk where a fallback assumed to be safe turns out not to be, right when it’s needed most.

The Metaphor, Fully Extended

Building Element	Expand-Contract Pattern Concept
Building the new wing first, alongside the still-functioning old wing	The expand phase, adding new structure alongside the old
Moving tenants over to the new wing once it’s ready and proven livable	The migrate phase, moving consumers over while the old structure still works
Demolishing the old wing only once every tenant has genuinely moved out	The contract phase, removing old structure only once migration is complete
Demolishing the old wing before the new one is ready, leaving tenants stranded	A risky, single-step cutover attempted without the expand-contract sequencing
A building manager tracking exactly how many tenants have actually moved, before scheduling demolition	AI-assisted migration progress tracking monitoring real consumer migration completion

For Beginners: What to Actually Do

Default to the expand-contract pattern for any genuinely breaking schema change, rather than attempting a single-step cutover.
Never remove old structure until you’ve genuinely confirmed every consumer has migrated, not just assumed enough time has passed.
Use AI-assisted migration progress tracking to know precisely when it’s safe to proceed to the contract phase.
Notice that this pattern directly depends on the compatibility disciplines covered in Article 14 during its migrate phase.

For Practitioners and Leaders: The Deeper Layer

Establish expand-contract as your organization’s default pattern for breaking schema changes, rather than allowing risky single-step cutovers.
Use AI-assisted migration planning to automatically generate safe expand-contract sequences for proposed breaking changes.
Use AI-assisted rollback readiness checking to verify the old structure genuinely remains a safe fallback throughout the migration.
Budget realistic time for the migrate phase, since rushing consumer migration to hit an arbitrary deadline undermines the whole pattern’s safety benefit.

Quick Recap

The expand-contract pattern breaks a breaking schema change into expand, migrate, and contract phases, avoiding a risky, instantaneous cutover.
This directly parallels building a new wing, moving tenants over, and only then demolishing the old wing once it’s genuinely empty.
AI-assisted migration planning and progress tracking can now generate safe sequences and monitor real consumer migration completion.
AI-assisted rollback readiness checking verifies the old structure genuinely remains a safe fallback throughout the process.

Where This Fits in the Series

Article 15 covered schema change review and governance. This article covered actually moving tenants to the new wing — the expand-contract pattern. Article 17 looks at the condemned wing, safely removing what’s no longer needed.