AR5: Legacy modernisation: strangler fig, anti-corruption layers and safe migrations
Moving data safely
🎯You'll be able to
Plan a data migration that can be run more than once, checked by counts, and undone, using the expand-and-contract approach for changes to shared data.
🏠The everyday picture
Moving house, you label boxes, count them into the van and count them out at the new place, before throwing away the old cupboards.
📘What it really is
- Copy, check, switch, clean up: copy the data to the new home; check it matches; switch readers; remove the old copy later.
- Idempotent migration: running it twice gives the same result, with nothing copied twice. Re-runs are then safe after a failure.
- Reconcile with counts: source count, target count, copied, unchanged, and whether they match. Write them to a report.
-
Expand and contract (also called parallel change): add the new shape alongside the old (expand), move readers and writers over, then remove the old shape (contract). Each step is small and reversible.
-
Don't move more than needed. If a message carries the phone number it needs, the service doesn't need a copy of every customer.
📝A worked example
Input: the notify service needs the four message templates that live in the monolith.
Steps:
- Read the monolith's
templates.jsonand the service's file (empty at first). - Copy templates that are missing or different; count copied and unchanged.
- Write
data/migration-report.json:{ source: 4, target: 4, copied: 4, unchanged: 0, matching: true }. - Run it again:
copied: 0, unchanged: 4, matching: true.
Expected output: a migration that can be repeated safely, with a report that proves the two sides match.
🌍Where it's used
- Banks reconcile account counts and balances to the paisa after moving data between systems.
- Database changes in busy systems use expand and contract to avoid downtime.
- Cloud moves copy data, verify checksums, then switch.
📝Case scenario
A clinic chain moved patient appointments to a new system with a script that failed half-way. Re-running it created duplicate appointments for the first half, and patients turned up for slots that had been double-booked. A migration that skipped records already copied would have been safe to re-run.
🖱️Try it
Write the steps for moving one table in a project of yours to a new shape with expand and contract. Success: each step can be undone, and nothing breaks between steps.
⚠️Common mistakes
- One-shot scripts. Sign: a script that can't be re-run. Fix: idempotent copies that skip what's done.
- No reconciliation. Sign: "it ran without errors". Fix: counts on both sides in a report.
- Moving everything. Sign: copying all customers "just in case". Fix: move only what the new home owns.
🛠️For your project
Project 2's test 9 runs your migration twice into a temporary folder and checks the counts and the report.
✅Quick check
What makes a migration idempotent?
Show the answer
Running it again gives the same result, with nothing copied twice.
What are the steps of expand and contract?
Show the answer
Add the new shape beside the old, move readers and writers over, then remove the old shape.