Insights · Modernization

Monolith migrations fail at the data layer

CDCETLStrangler fig

Key takeaway

Data integrity decides the migration, not the service map: design dual-write, CDC and reconciliation as first-class architecture.

The failure pattern

Watch a monolith-to-microservices programme and you’ll usually find the same sequence. Months of domain modeling produce beautiful service boundaries. Teams form around them. The first three services are extracted behind an API gateway, the demo impresses, confidence rises, and then someone asks the question that stalls the programme for a year: when a customer updates their address in the new service and the nightly batch still writes to the old database, which one is true?

By that point the answer is expensive. The migration didn’t fail at service boundaries; it failed at the seam nobody designed: the data layer during coexistence. This is the risk Martin Fowler’s strangler-fig argument names: big-bang replacements take too long, users can’t wait, and by the time the replacement arrives the requirements have moved (Fowler, “StranglerFigApplication”). The incremental path only works if the data seam is engineered; the pattern doesn’t build it for you.

Why the data layer is the hard part

A monolith’s database is not a storage detail; it’s the integration fabric. Years of foreign keys, triggers, stored procedures and reports encode business rules nobody remembers writing. Extract a service means extracting a slice of that fabric, and the slice doesn’t come clean. Three properties make it genuinely hard:

  • Shared tables. A single customer table serving six modules. Which service owns it? Every answer reshapes boundaries you thought were settled.
  • Transactional spans. Business operations that cross the future service boundaries inside one ACID transaction. After extraction they cross the network, and “distributed transaction” is a phrase best kept out of your architecture.
  • Hidden readers. Reports, exports, integrations and that one script in cron read tables directly. They never appear on the service map; they appear in the incident channel.

The three mechanics that hold it together

On the E-Tax modernization for Rwanda Revenue Authority, the data-integrity design got as much architecture attention as the service decomposition, and in hindsight it deserved more. Three mechanics did the work:

1. Dual-write with an escape hatch

During coexistence, writes go to both the legacy store and the target service, but never as naive synchronous double-commit, which couples the migration’s availability to two systems at once. The write path treats the legacy system as authoritative for as long as it serves live traffic, with the new path validated against it before the roles flip. The shape is long-established practice — Danilo Sato’s “parallel change, also known as expand and contract” (martinfowler.com, “ParallelChange”) — applied to state instead of schema. Reversibility is the design requirement: at any phase, you can shift traffic back without losing a transaction.

2. CDC as the sync fabric

Change-data-capture (Debezium reading the legacy Oracle store into Kafka) synchronizes state in the other direction: legacy changes flowing to the target platform without touching the monolith’s code. Debezium is “an open source distributed platform for change data capture” that “records all row-level changes within each database table in a change event stream” (Debezium documentation) — read once from the transaction log, delivered in order, fanned out by the event backbone. The CDC pipeline is infrastructure, monitored and versioned like infrastructure, with schema changes handled through the evolutionary-database discipline: every change a versioned migration that keeps the store “backwards compatible with all previous application releases that are live in production” (Fowler & Sadalage, “Evolutionary Database Design”).

3. Reconciliation as a continuous control

Not a post-cutover audit: a standing reconciliation job comparing legacy and target records on a schedule, with defined tolerances and an escalation path for drift outside them. Reconciliation output is a governance artifact, reviewed at the phase gates that decide whether traffic shifts further. A mismatch is a stop-the-line event, not a ticket.

Rule of thumb

If your migration plan’s data section is shorter than its Kubernetes section, the plan isn’t finished. Move traffic, never integrity.

Signals you’re in trouble

  • The plan says “migrate the database” as one line item in a phase.
  • Nobody can enumerate the systems that read each major table.
  • “We’ll run a reconciliation report at the end” is the integrity story.
  • The first extraction target is the most business-critical domain “to prove value”.

That last one deserves its own note: sequencing by risk means proving the machinery on a domain where failure is survivable. On E-Tax, low-risk domains moved before core tax functions. The pattern is Martin Fowler’s strangler fig — small additions built on top of, yet separate from, the legacy system, where “there isn’t so much risk involved when we introduce the new software” (Fowler, “StranglerFigApplication”): growth around the load-bearing walls, not through them.

Applied: a national tax platform

The E-Tax programme wrapped these mechanics in a five-phase plan over roughly 24 months, each phase ending in an approval gate where data integrity was a first-class criterion. The full case study, including the dual-write design, the CDC pipeline from Oracle and the governance that kept it coherent, is here: Modernizing a national tax platform without stopping it.

Discuss a migration you’re planning

Sources