Strangler migrations with a measurable rollback path.
A strangler rollback is safe only when the old implementation can resume ownership of current compatible state. Use stable routing units, one writer per unit, and explicit reconciliation gates; changing traffic alone cannot undo committed writes or external effects.
Inside this article 6 sections +
A strangler migration has a credible rollback path only when the old application can safely resume responsibility for the affected customers and their latest state. Switching a proxy back is straightforward; reconciling writes, identifiers, and external side effects is the difficult part.
Design the rollback exercise before directing production traffic to the replacement. Define the unit being moved, the owner of writes at each stage, and the point after which returning to the old behavior requires a separate repair operation.
Choose a routing unit that preserves consistency
Suppose a SaaS product is replacing its document approval workflow. Routing a random percentage of individual requests can send creation to the new implementation and approval to the old one. If they interpret state differently, the customer experiences a broken workflow even though each endpoint is healthy.
Prefer a stable unit such as account, document, or workflow version. All operations for that unit should follow the same ownership decision. Keep the routing record observable and versioned, and specify what happens to requests already in flight when the decision changes.
Shadow reads can compare outputs before cutover, but shadow writes are dangerous if they trigger email, payments, or downstream jobs. A comparison path should suppress external effects and use a controlled data copy. Successful comparison is evidence about behavior, not proof that the new system can own production state.
- Before transferOld writer owns state
New implementation compares read results.
- Transfer checkpointDrain and reconcile
Record the final applied change and block conflicting writes.
- Injected failureNew writer stops
Pause admission and inspect accepted operations.
- Return checkpointOld writer resumes
Only after compatible state and side effects reconcile.
Describe the write contract during coexistence
Make one implementation authoritative for each routing unit. If the old system still owns writes, the replacement can call it through a compatibility interface. If the new system owns writes, the old system may need a maintained projection that remains capable of resuming the workflow. Neither arrangement is free; choose which temporary complexity the migration can support.
Define operation IDs that survive retries and routing changes. A user who retries an approval after a timeout should receive the result of the original operation rather than create another approval. Preserve these identifiers through both implementations and every side-effecting integration.
Use backward-compatible schema changes during the rollback period. Adding a new optional field is different from changing the meaning of an existing status. If the old code cannot represent a state created by the new code, record that incompatibility as a boundary to rollback and prevent its accidental use during the reversible phase.
Measure return readiness, not just application health
Alongside error rate and latency, track unapplied changes, mismatched business states, in-flight operations, and unresolved external effects. Row counts alone do not establish readiness. Two systems can contain the same number of documents while disagreeing about which approvals are final.
Set cutover gates around the consequences of these differences. For a legally significant approval, an unexplained status mismatch may block the transfer entirely. For a derived preview, a bounded rebuild may be acceptable. The product owner must understand the distinction; “eventual consistency” is not an operational acceptance criterion.
Record the time required to detect the injected failure, stop admission, reconcile state, change routing, and confirm user behavior. These are measurements from the rehearsal once it is run. Until then, they are fields to collect rather than promised recovery times.
For an account routed to the replacement, rollback involves more than flipping its traffic flag. This sequence makes the state handoff an explicit part of the return decision.
- Quiesce the affected writer
Bound new writes for the routing unit and identify operations still in flight or waiting on a provider.
- Reconcile committed outcomes
Verify that the old path can represent accepted state and that external effects have known ownership.
- Return the routing unit
Switch only after the compatibility checks pass, then confirm the customer outcome through the old path.
Keep the exact sequence appropriate to the product’s write and availability contract. An account-level pause may be acceptable for one capability and unacceptable for another; the exercise should reveal that choice before an incident.
Run the failure exercise at an inconvenient moment
Interrupt the new implementation after it commits an approval but before it returns a response. Retry the request, then initiate rollback. Check that the old implementation sees the committed approval, the notification is not sent twice, and the client can discover the final outcome.
Repeat with a delayed replication consumer and an incompatible new state deliberately blocked by policy. Verify that the rollback controller refuses to proceed when its gates fail. A safe refusal with a clear repair path is preferable to reporting a successful rollback while customer data disagrees.
Keep the exercise scoped to a nonproduction environment or an explicitly controlled cohort. Use test recipients and sandbox integrations for external effects. The aim is to expose missing coordination without creating real customer actions as a side effect of the test.
Commission a migration rehearsal before customer traffic
Scope the first architecture engagement around a named migration unit, such as an account cohort and one write path. Specify which system owns writes during coexistence and which customer state must survive a return to the old path. The expected deliverable should include that ownership decision, a compatibility map, and a rehearsal that can demonstrate the return conditions in a controlled environment.
Ask for the inputs, procedure, observations, and unresolved gaps from the rehearsal. A receiving engineer should be able to follow the sequence, identify the point where rollback stops being safe, and explain how in-flight operations are reconciled. Include an estimate of the recurring coexistence work. Maintaining two paths has costs in monitoring, schema compatibility, on-call knowledge, and eventual retirement that belong in the decision before rollout.
A design engagement fits when the migration boundary or write contract remains open. A scoped implementation fits once the team accepts that contract and can provide a representative environment. Continuing engineering capacity may be needed when several product areas must move while normal development continues. We can make the first rehearsal the point where you decide whether the proposed migration is ready for that larger commitment.
Retire the old path when the evidence is sufficient
Coexistence creates operational work: duplicate monitoring, compatibility code, synchronization, and two implementations to understand. Give that work an owner and an exit condition. Once the reversible period closes, remove unused routes and credentials deliberately and retain the audit evidence needed to explain historical operations.
The shared database migration guide establishes data ownership before this stage. An architecture review can challenge the migration unit and return assumptions. Architecture design should produce a rollback procedure whose gates, measurements, and limits are visible before the first customer moves.