Migration

Planning a rollback before you migrate anything

A rollback plan is the part of a migration that, done well, nobody ever needs to use, which is exactly why it tends to get skipped when time is tight. Skipping it is a mistake specifically because the cost of needing a rollback and not having one is much higher than the cost of preparing one that goes unused.

The starting assumption for a good rollback plan is that the new provider will behave differently from the old one in at least one way you did not anticipate, no matter how thoroughly you tested beforehand. That is not pessimism, it is just an honest description of how integrations with external systems tend to go. Planning around that assumption, rather than around the hope that testing caught everything, produces a better plan.

A rollback plan for a location data provider switch should cover:

  • A fast switch mechanism. Whether that is a feature flag, an environment variable, or a configuration value read at request time rather than baked into a deployed build, the old provider's credentials and endpoint should stay valid and ready to use again without a code deployment, for some defined window after cutover
  • A clear trigger condition. Decide in advance what specifically would justify rolling back: an error rate above some threshold, a specific category of request failing, or a certain volume of user complaints, rather than leaving the decision to be made under pressure with no agreed bar
  • A rollback owner. One person or a small group who is explicitly responsible for deciding to roll back, so the decision does not stall while multiple people wait for someone else to call it
  • A defined expiration for the rollback window. Keeping both providers' credentials live indefinitely defeats the purpose of migrating; set a specific date after which the old provider's access is retired for good

Because My Geocode's compatibility hosts reproduce a provider's exact request and response shape, a rollback in a compatibility-based migration is often just a configuration change back to the old host and key, without needing to redeploy different parsing code, which shortens how long a rollback actually takes to execute if it is needed. That said, this cuts both ways: it also means testing that a rollback works, not just assuming it does, is worth doing deliberately once during the planning phase, since an untested rollback path is not meaningfully different from having no rollback plan at all.

It is also worth deciding what happens to data or requests processed during the period you are rolling back from. If a batch job ran overnight against the new provider before an issue was detected the next morning, does that batch need to be reprocessed, or is the discrepancy acceptable. Deciding this in advance, rather than during an actual incident, removes one more decision from an already stressful moment.

A migration plan that only describes moving forward is, in a real sense, an incomplete plan. The rollback half is what turns a migration from a one-way bet into a considered decision that can be reversed cleanly if the evidence calls for it.