How to migrate a live product without losing what works
A practical framework for preserving behavior, moving data and proving the replacement before retiring the original.
Treat migration as a sequence of evidence-backed transitions, with explicit data ownership, compatibility and recovery at each step.
Define the reason and the behavior to preserve
A migration moves a working responsibility from one implementation to another. It may replace a database, an application component or an external provider. The reason should be specific enough to evaluate: remove an observed capacity limit, support a needed capability or reduce a recurring operational burden. “Modernize the stack” leaves the team without a useful completion criterion.
Write down the customer behavior that must survive the transition. Include ordinary use, unusual but valid records and failure cases. Existing behavior may be undocumented, particularly in a product that grew through rapid experimentation. Some apparent oddities encode real customer needs. Investigate before removing them.
For a hypothetical reporting product, an old export may use a particular ordering that customers rely on when combining files. A replacement can produce mathematically equivalent data and still disrupt their workflow. A migration inventory should therefore include observable outputs and integration expectations, not only internal database fields.
Move one bounded responsibility at a time
Microsoft’s strangler fig pattern describes gradually replacing functionality while an intermediary directs requests to the appropriate implementation. This can make a migration more manageable by allowing old and new behavior to coexist. The routing layer itself requires care: it becomes part of the path customers depend on.
Choose a slice that can be evaluated independently. A read-only report may offer a simpler first transition than a workflow that changes several related records. Simpler does not mean trivial. Authentication, access boundaries and output correctness still need to hold. The purpose of the first slice is to learn how the transition behaves while keeping its consequences understandable.
Define what happens to a request during the overlap. Does it go entirely to the old implementation or entirely to the new one? Can a user switch between them midway through a task? Which version owns any work already in progress? Ambiguous routing can produce defects that exist only during migration, precisely when the team is handling additional complexity.
Make data ownership explicit
Data is often the hardest part of a live transition. Copying records creates a snapshot, while customers continue changing the source. The plan must explain how changes made during the copy are captured and when the destination becomes authoritative. Two writable copies without a clear reconciliation rule can diverge.
Create a mapping for fields and relationships. Record transformations, unsupported values and the handling of incomplete records. Test the mapping with representative edge cases. Counts are useful but insufficient: two datasets can contain the same number of rows while associating them with the wrong customers or changing their meaning.
Use checks tied to product rules. PostgreSQL documents constraints that can enforce properties such as uniqueness and referential relationships. Where applicable, these help detect invalid destination data, but they cannot prove that every business meaning was preserved. Reconcile important totals, inspect selected records and verify the customer workflows that depend on the migrated information.
Design recovery before cutover
Recovery depends on which changes have already occurred. Before the destination accepts writes, returning traffic to the original may be relatively simple. After new records or new data shapes exist only in the destination, routing backward can lose work or expose incompatible behavior. A rollback plan needs to state this boundary explicitly.
Decide whether each stage can be reversed, repaired forward or paused. Keep the old implementation compatible for the period in which it may be needed. Avoid removing fields or data until the team has established that no active path still relies on them. A delayed cleanup is often easier to reason about than a rushed attempt to reconstruct deleted information.
Prepare and test the relevant backup and restore procedure in an isolated environment. PostgreSQL describes several backup approaches with different characteristics; the appropriate choice depends on the system. A stored backup is only one part of recovery. The team must also know how to restore it, validate it and reconnect the application to the recovered state.
Prove the transition and finish it
Compare the replacement against explicit acceptance criteria. For a read path, this may include output agreement, response time and correct access restrictions. For a write path, include durability, repeated requests and the behavior of interrupted operations. A faster replacement with subtly different results has not necessarily met the migration’s purpose.
Where suitable, introduce the change to a limited cohort and observe it before widening access. Google’s canary guidance emphasizes evaluating a limited rollout against meaningful signals. Choose a cohort that exercises the relevant behavior, and allow enough time for delayed work to complete. A successful initial response does not prove a later job finished correctly.
Finally, remove the overlap deliberately. Confirm that traffic, scheduled jobs and integrations no longer depend on the old path. Retain required records through the product’s established retention process, then retire obsolete infrastructure and update operational documentation. Migration is complete when the new path serves the intended behavior and the team can operate it without relying on a forgotten predecessor. Preserve the evidence and remaining limitations so the next architectural decision starts from a trustworthy account of what changed.
Frequently asked questions
How do we migrate a product while customers are using it?
Define the behaviour to preserve and move one bounded responsibility at a time. Keep compatibility and data ownership explicit, verify the transition and prepare recovery before directing customers to the new path.
What makes data migration particularly risky?
Old and new components may both attempt to write the same records, or disagree about their meaning. Define which component owns each write and test compatibility and correctness before switching ownership.
When should rollback be planned?
Before cutover. Specify what can be reversed, what data changes cannot simply be undone and how the team will detect and recover from a failed transition. Test the recovery plan as well as the forward migration.