Monolith → Microservices

One extraction, start to finish — sixteen steps, how you know each is done, and the way back

A migration that works is not one big project. It is the same small project repeated: take one capability out of the monolith and put it into a service, with the system running the whole time. Each repetition has the same sixteen steps, in the same order. The column that matters most is the last one. It says how to undo each step, and for almost all of them the answer takes minutes. Later sections cite the steps by number.

Before the first extraction: the reason and the candidate

Most migrations begin with a picture of the destination — a diagram of twelve services — and work backwards. That ordering is why so many of them run for two years and end with eight services, a monolith that still holds the important logic, and a team slower than when it started. The ordering that works begins with step 1: a named constraint you can measure today. Each reason people give for a migration either passes that test or points at cheaper work, and the table sorts the common ones.

Step 2 picks the first candidate, and it should be neither the hardest piece nor the most important one. The first extraction is a rehearsal. Its job is to teach the team the pipeline, the tracing, the on-call rota and the data handover while a mistake is still cheap. So it wants few callers, a clear boundary and a small blast radiusblast radiushow far the damage spreadsHow much of a system is affected when one thing goes wrong — a bad deploy, a crashed process, a leaked credential, an agent’s mistake. It is kept small with boundaries: separate processes, narrow permissions, staged rollouts. The trade-off is that every boundary which contains a failure also costs something to cross.All terms if it fails. The table scores the usual candidates.

From the second extraction on, order by the constraint from step 1, not by convenience. And keep each one small enough to land within a few weeks. An extraction that runs for six months has stopped being reversible in any practical sense, because the monolith it came from has moved on underneath it.

Six ways to move code without stopping the system

The best-known pattern has a botanical name. During a holiday in the Queensland rain forests in 2001, Martin Fowler saw strangler figs. The fig starts as a seed in a nook of a host tree, grows down to the ground and up to the light, and can end up standing on its own where the host tree was. A couple of years later he used it as a picture of how his colleagues replaced legacy systems, in a short post called “Strangler Application”. He later renamed it “Strangler Fig Application”, because people kept the violent word and forgot the plant. In August 2024 he rewrote the post, and the new version names four activities that Ian Cartwright, Rob Horn and James Lewis defined for any gradual replacement. Understand the outcomes you want. Decide how to break the problem into smaller parts. Deliver the parts successfully. And change the organisation so that this can go on.

The same post makes an argument teams often resist. A gradual replacement needs transitional architecture: facades, sync jobs and switches that exist only while old and new run side by side, and are deleted afterwards. It looks like waste. Fowler’s answer is that the reduced risk and the earlier value outweigh its cost. Steps 4, 9 and 12 are exactly this kind of code. Budget for them instead of resenting them.

The facade goes in first, before anything is extracted (step 4). With the facade in place, the first extraction is a routing change, and so is its rollback. Without it, the first extraction is a change to every caller, and the rollback is another change to every caller. Sam Newman’s “Monolith to Microservices” (2019) collects the strangler fig and five related patterns for moving code, and each fits a different situation:

Branch by abstraction: a seam inside the code

A facade only sees what crosses the edge of the system. Much of what you want to extract is called from inside it — a pricing function used by checkout, invoices and the admin pages. Branch by abstraction handles that case. Paul Hammant gave the technique its name while arguing for trunk-based developmenttrunk-based developmenteveryone merges into one branch dailyA way of working in which every developer merges small changes into one shared branch at least once a day, hiding unfinished work behind feature flags rather than in long-lived branches. It needs a test suite that answers in minutes and is trusted; without one it only merges breakages faster.Full article →All terms, crediting Stacy Curl with the idea, and Fowler described the steps in January 2014. Put an interface in front of the old code. Move every caller onto the interface, one at a time. Build the new implementation behind the same interface — here, a client that calls the new service. Switch callers over with a flag. When nothing uses the old implementation, delete it, and later the interface too if it no longer earns its place. Every commit along the way keeps the system building and releasable, so no long-lived branch ever has to be merged.

Parallel run: proving the new code before trusting it

A rewrite is only as good as its fidelity to the old behaviour, and the old behaviour is rarely written down. A parallel run (step 10) measures it instead of guessing. Every request, or a sample of them, goes to both implementations. The user gets the old answer. The new answer is compared with it, and every difference is recorded with enough context to debug. GitHub built a library for this, Scientist, and described using it to replace the code that merges pull requestspull requesta change proposed for reviewA request to merge one branch into another, where the change is reviewed, discussed and checked by the pipeline before it reaches the main branch; GitLab calls the same thing a merge request. Its cost is waiting: a pull request that sits unreviewed for days is where long-lived branches and painful merges come from.Full article →All terms. After four days of fixing what the experiment found — including a feature missing from the new merge engine altogether — the new code ran for 100% of requests for 24 hours with no mismatches and no slow cases. Tens of millions of merges had been checked before the old path was switched off. Khan Academy did the same at the edge of its system and called it side-by-side testing: its gateway sent most traffic for a request to the monolith and some to the new services, and compared the results until every difference was fixed.

Splitting the data — the migration itself

Extracting the code is a week of work. Extracting the data is the migration. It is also where teams that skipped this section end up with two services on one database — the outcome the whole exercise was meant to avoid. Newman describes three orders: split the database first, split the code first, or do both at once. He warns against doing both at once. In his experience code first is the most common, because it shows results sooner. Its usual failure in practice is stopping there, with the new service still reading the monolith’s tables.

The sixteen steps avoid both traps by moving one thing at a time. The split starts inside the monolith, where it is cheap (steps 6–7). Separate the module’s tables logically — same database, its own schema, no joins or foreign keysforeign keya column pointing at another table’s rowA column whose value must match the key of a row in another table — an order’s customer id must name a customer who exists. The database refuses any row that breaks the rule, whoever writes it; across services, where no single database can check it, the rule becomes the application’s job.Full article →All terms across the line. This alone surfaces every hidden dependency, because every crossing now fails a check, and each one is fixed while the old system keeps running. Then the data is copied and kept in sync (9), reads move (10–11), writes move (12), the last readers move (13), and only then is anything deleted (14).

GitHub ran exactly this at scale between 2019 and 2021, on the database cluster that held users, repositories, issues and pull requests. First came virtual partitions. Tables that belong together were grouped into schema domains, listed in a plain YAML file in the Rails application. Two linters enforced the groups: one failed any query that referenced tables from two domains, the other any transaction that spanned them. Existing violations were annotated as exemptions, which turned them into a visible backlog. A domain with no exemptions left was ready to move. The physical move used Vitess, or a custom cutover over MySQL replication that switched writes in a few tens of milliseconds, at the quietest hour of the day; one cutover moved 130 of the busiest tables at once. In 2019 the cluster answered 950,000 queries a second. In 2021 the same tables, spread over several clusters, answered 1,200,000 — and the average load on each host had halved.

Not every database splits along clean lines, and Newman’s book names the patterns for the awkward cases. These seven come up in almost every migration:

Reports are where a data split is usually found to be unfinished (step 13). A report that joins six modules’ tables worked for years because everything sat in one database. After the split there are two honest answers. Either the report calls the services that own the data, or it reads an analytics copy fed by events or by the database logs. Newman recommends a schema built for reporting rather than queries against the operational stores. Either way, find every reader before step 14. The one monthly export nobody remembered is a classic cause of a rollback on the first of the month.

The model and the teams: the anti-corruption layer and Conway’s law

The new service will need data from the old system, and the old system’s model is usually shaped by fifteen years of accidents. If the new service speaks that model, it inherits it permanently, and there was little point extracting it. Eric Evans named the defence in “Domain-Driven Design” in 2003: an anti-corruption layer. It is a translation boundary — a thin piece of code that speaks the legacy model on one side and the new service’s model on the other, and belongs to the new service. It is deliberately ugly, deliberately isolated and deliberately temporary. When the legacy source finally goes away, one component is deleted, instead of a model being unpicked from every file. Here is what it typically translates:

Melvin Conway observed in 1968 that a system’s structure ends up mirroring the communication structure of the organisation that built it. In a migration this is not a curiosity; it is the strongest force in the room. If four teams share ownership of the extracted service, it will grow four internal factions and a coordination meeting, and it will not be independently deployable whatever the diagram says. Used deliberately, the same force becomes a tool. Jonny LeRoy and Matt Simons named it the inverse Conway maneuver in 2010: change the team boundaries to the ones you want the services to have, and the architecture follows.

It also sets the honest upper limit on the migration. You cannot end with more services than you have teams to own them, and a service nobody owns rots faster inside a distributed system than it ever did inside the monolith. So step 3 includes an on-call rota on purpose. The owning team runs the new service from the day it takes its first request — Amazon’s rule, in Werner Vogels’s words, “You build it, you run it.”

Running the migration: capacity, pace, and when to stop

The migration competes with feature work for the same people, and that competition is decided by whoever is in the room when the quarter is planned. A migration run in the background by whoever has spare time takes three years and never finishes. A migration run as a total freeze on features loses the argument at the first commercial deadline. What survives is a stated share of capacity — one team, or a fixed fraction of every team’s quarter — with each extraction landing as a visible result rather than as progress on a plan.

Stop the old code growing while you move it. Khan Academy’s rule during its rewrite was that every new feature written in the old Python code needed the personal approval of its head of engineering, because every new line was one more line to port. The same project measured its progress by what had moved, not by what had been built: the share of traffic served by the new backend, the number of APIAPIApplication Programming Interface — contract between programsThe rules one program follows to call another: which requests it may send, in what shape, and what comes back. To the caller it is a contract — everything behind it stays a black box, which is exactly what lets the other side be rewritten without breaking you.Full article →All terms fields completed, and the scope that grew as the work was understood. The table lists the measures that tell a working migration from a stalled one.

Nothing in the pattern requires the monolith to disappear, and treating its disappearance as the goal is how a migration outlives its justification. Each extraction was justified by a constraint. When the remaining pieces are not blocking anything, the remaining extractions have no argument behind them except symmetry. A permanent hybrid — a few services around a well-modularised core that still holds most of the domain — is a common and respectable end state. In most organisations it is also the point of best return: the parts with a real need for independence have it, and the rest are not paying for a network they never needed. SoundCloud’s engineers said as much in 2015: some of what the monolith did was so small and stable that it might be cheaper to keep it there forever.

Measure the migration against the constraint you named in step 1, not against the number of services. If payments now ships twice a week instead of once a month, that extraction paid for itself, and you can say so with a number. If the service count went from one to nine and lead time did not move, nine services are not progress. They are nine deployment pipelines.

Five cases, and what each one was missing

The five cases span twenty years, from the migration that shaped the word to one that finished in 2021. Each is told by the people who did the work, and each shows a different step of the sixteen carrying the weight.

Amazon’s is the story the vocabulary came from. In a 2006 interview Werner Vogels described Obidos, the application that had held all of Amazon’s business and display logic since the company started. For years the scaling effort went into the databases behind it, until in 2001 the front end itself could no longer scale. The deeper problem was sharing. The databases were shared by many teams and processes, so nothing had isolation and nothing had a clear owner, and both the front end and the back end were stuck. The answer was a service-oriented architecture with one rule above the others: data is encapsulated with the logic that operates on it, reachable only through the service’s published interface, with no direct database access from outside. It grew into hundreds of services. Read the rule again and notice what it does not mention. It says nothing about how small a service should be. The constraint was ownership, and so was the fix.

Netflix started in August 2008, when a major database corruption meant it could not ship DVDs for three days. The lesson it drew was to move away from vertically scaled single points of failure such as one relational database in its own data centre. It chose not to lift the existing systems into the cloud unchanged, because that would have moved all the old problems with them. Instead it rebuilt: from a monolithic application to hundreds of microservices, with a denormalised data model on NoSQLNoSQLdatabases that are not SQL tablesAn umbrella name for databases that do not store relational tables queried with SQL: key-value, document, wide-column and graph stores. Most of them place each record on a machine by a key chosen at design time, which makes queries carrying that key cheap at any size and most other queries expensive or impossible.Full article →All terms stores. Every customer-facing system had moved before 2015. Billing and customer data took the time after that, and the last data-centre pieces were shut down in early January 2016 — seven years after the start. The part that took longest was not the services. It was the data with the strictest rules attached to it.

Where it degrades

A migration rarely fails on one day. It fails by stalling: half the steps done for many capabilities, and all the steps done for none. Almost every stalled migration shows several of these:

• A big-bang rewrite beside the running system, where all the risk arrives on one date and the old system keeps moving.
• No named constraint, so success is counted in services created (step 1).
• Code extracted and the database left shared — a distributed monolithdistributed monolithservices that must still ship togetherA system split into services that still cannot be deployed independently — they share a database, must be released in a fixed order, or call each other synchronously for every request. It keeps the coupling of a tangled monolith and adds network failures, which is why it is worse than either a monolith or real microservices.Full article →All terms with extra steps (steps 9–14 skipped).
• Starting with the hardest, most central capability, so the team learns the mechanics where mistakes cost most (step 2).
• No facade, so every extraction and every rollback is a change to every caller (step 4).
• Extractions that run for months, which stop being reversible because the monolith moves underneath them.
• Dual writes with no reconciliation, so the two stores drift apart silently.
• A parallel run that also performs the side effects, doubling what it was meant to observe (step 10).
• The new service speaking the legacy data model, which imports the mess it was meant to escape.
• Old tables dropped before every reader has moved, found by the monthly report (steps 13–14).
• New features still landing in the old code, so the work to port grows faster than the port.

The honest limit is that the method makes a migration safe, not short. Every step on this page exists to keep the system working and the way back open, and each of them costs time: a facade, a sync, a parallel run, a month of logs before a table is dropped. Netflix took seven years. A team that needs the result by a fixed date cannot buy it with a better pattern, only with a smaller scope. Most of the time the right scope is smaller than the plan — a handful of extractions, each paying for itself, around a monolith that stays.

The practical check takes an afternoon. Ask for the constraint behind the migration and its number today. List the extractions in progress and the step each one has reached; more than two in progress at once is a warning. Check whether a facade sits in front of the monolith. For each extracted service, find out whether its old tables still exist, and who still reads them. Search for code that writes to two stores in a row. Count the new features added to the monolith last quarter. And for the next extraction, write down its way back before writing any code.

When to use it

Related pages

• DevelopmentMonolithA monolith is an application that is built, tested and deployed as one unit, whatever its size and however its code is organised inside. Most complaints made about monoliths are really about the missing boundaries inside one — a different problem with a cheaper fix — and a monolith with real module boundaries is the right default for most systems. The page opens with sixteen common complaints and where each one actually lives, then covers the two axes every architecture argument confuses, why one deployable is the default and the best argument against it, drawing and enforcing module boundaries, running a large monolith, where it genuinely runs out, five documented cases, and where it degrades.
• DevelopmentMicroservicesMicroservices are an architecture in which one system is built as a set of small services, each deployed on its own, owning its own data and owned by one team. Independent deployment is what the style buys, and every call that now crosses a network is what it costs. The page opens with sixteen problems the network adds and the pattern that answers each, then covers the nine characteristics the term was defined by, what you need before the second service, data across services, calls between services, running many of them, five documented failures, and where it degrades.
• DevelopmentAPI DesignAPI design is the work of deciding what other programs may send to yours, what comes back, and which of those promises you will keep for years. Anything a consumer can observe becomes part of the promise, and you cannot take it back alone. The page opens with sixteen decisions every HTTP API makes, the default to take and what changing each later costs, then covers what the contract includes, methods, status codes and errors, behaviour under retries and load, who may do what, changing a published API, five documented cases, and where it degrades.