zero gravitySOLUTIONS
← All insightsARCHITECTURE / MIGRATION EXERCISE

Strangler migrations with a measurable rollback path.

QUICK ANSWER

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.

Original rollback rehearsal · one account cohort
  1. Before transferOld writer owns state

    New implementation compares read results.

  2. Transfer checkpointDrain and reconcile

    Record the final applied change and block conflicting writes.

  3. Injected failureNew writer stops

    Pause admission and inspect accepted operations.

  4. Return checkpointOld writer resumes

    Only after compatible state and side effects reconcile.

The rehearsal measures a safe return of ownership. It does not assume that changing a routing flag repairs data.

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.

A return path needs state evidence
  1. Quiesce the affected writer

    Bound new writes for the routing unit and identify operations still in flight or waiting on a provider.

  2. Reconcile committed outcomes

    Verify that the old path can represent accepted state and that external effects have known ownership.

  3. Return the routing unit

    Switch only after the compatibility checks pass, then confirm the customer outcome through the old path.

If the old implementation cannot represent a committed state, the diagram stops at reconciliation. Traffic routing cannot repair that incompatibility.

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.

FROM INSIGHT TO ACTIONSoftware architecture consulting

Make the first migration slice prove the return path.

We can design the coexistence contract, implement a bounded slice, and document the rehearsal evidence and operating work needed for a wider migration.

Explore architecture consultingDiscuss your architecture

Start with your goals.
We’ll work through the next step together.