Migration Strategies

Why Migration Strategy Matters

The honest framing: a microservices migration is not a technical project. It is an organizational change that uses code as its medium. The architecture diagram is the easy part. The hard parts are deciding which team owns which service, how to migrate data without downtime, how to ship product features during the migration, and how to know when to stop.

Why big-bang rewrites fail

1. The monolith’s real specification lives in its code. Nobody can write it down before the rewrite starts — they discover it as the new system fails to handle case after case.
2. The product does not stop. Features ship to the monolith during the rewrite. The new system is always behind, never catching up.
3. There is no intermediate value. You spend 12 months and have nothing in production. Leadership patience runs out before code does.
4. Teams lose context. The engineers who knew the monolith leave. The new team rebuilds bugs because they never understood why the old code was “weird.”
5. Cutover is terrifying. Everything-or-nothing means a single bad day can lose customers, data, or both.

Joel Spolsky called this the single worst strategic mistake that any software company can make. He was not exaggerating. Every successful migration in this tutorial is incremental.

When NOT to Migrate

The cost of microservices is real and is often underestimated. You will need: a service mesh or equivalent, distributed tracing, centralized logging, a CI/CD pipeline per service, on-call rotations per team, contract testing, schema registries, secret management, blue/green or canary deploys, and the discipline to not share databases. None of that is free.

Here is a blunt heuristic table. If most rows are on the left, you do not have a microservices problem — you have a code problem. Fix that first.

In practice, most teams should not migrate. They should clean up the monolith. A modular monolith with clear internal boundaries gives you 80% of what microservices offer for 20% of the cost. Shopify, GitHub, Basecamp, and Stack Overflow all run very large modular monoliths in production. There is no shame in that.

Strangler Fig Pattern

Martin Fowler named this pattern after the strangler fig tree, which grows around an existing tree, slowly takes over its space, and eventually leaves a hollow shell where the host tree used to stand. The metaphor is exact: the new architecture surrounds the old one and the old one withers.

The four moves

1. Insert the proxy. Put nginx, Envoy, an API gateway, or a load balancer in front of the monolith. At this stage it does nothing — 100% of traffic still goes to the monolith. This is a no-op deploy with no risk.
2. Build the replacement. Pick one route or capability. Build it as a new service. It can read the monolith’s database, call the monolith’s APIs, or own its own data — depending on the slice.
3. Cut traffic over gradually. 1% → 10% → 50% → 100%, with monitoring at each step. Often you mirror traffic first — send the same request to both systems and compare responses, without using the new system’s response.
4. Delete the old code. Once 100% of traffic is on the new path and you have run that way for a couple of weeks, remove the monolith’s implementation. If you do not delete, you will have two systems to maintain forever.

Routing by path with nginx

# nginx in front of a strangling monolith.
# Old monolith on :8080, new services on their own ports.

upstream monolith     { server 10.0.0.10:8080; }
upstream catalog_svc  { server 10.0.1.20:9001; }
upstream checkout_svc { server 10.0.1.21:9002; }

server {
    listen 443 ssl;
    server_name shop.example.com;

    # Already extracted: send straight to the new service.
    location /products/ { proxy_pass http://catalog_svc; }
    location /checkout/ { proxy_pass http://checkout_svc; }

    # Canary: cookie-based, 10% of /search to the new service.
    location /search/ {
        set $backend monolith;
        if ($cookie_canary = "new") { set $backend search_svc; }
        proxy_pass http://$backend;
    }

    # Everything else still goes to the monolith.
    location / { proxy_pass http://monolith; }
}

Envoy and most service meshes give you the same shape with richer matching: route by header, by JWT claim, by request shadowing percentage. The mechanism does not matter. What matters is that traffic shifting is a config change, not a deploy.

Branch by Abstraction

This pattern was named by Paul Hammant and is the workhorse refactor of every successful migration. It looks like over-engineering until you have done it once and shipped a clean cutover with no downtime. Then it looks like the only sane way.

The shape is always the same:

1. Find every call site of the code you want to extract.
2. Introduce an interface (abstract class, protocol, function pointer — whatever your language gives you).
3. Move existing code behind the interface as OldImpl. Ship. Verify nothing changed.
4. Build NewImpl that calls the new service. Ship dark — behind a feature flag, default off.
5. Flip the flag for 1%, 10%, 100% of traffic. Watch metrics.
6. Delete OldImpl and the flag. The interface remains; the monolith now calls the new service for this capability.

# Step 1: define the seam inside the monolith.
class PricingService(Protocol):
    def price_for(self, sku: str, qty: int, country: str) -> Money: ...

# Step 2: wrap the existing tangled code in OldPricing.
class OldPricing:
    def price_for(self, sku, qty, country):
        # existing 400-line method, now reachable only via this seam
        return _legacy_price_calc(sku, qty, country)

# Step 3: new implementation calls the extracted service.
class NewPricing:
    def __init__(self, client: PricingClient):
        self.client = client
    def price_for(self, sku, qty, country):
        return self.client.quote(sku=sku, qty=qty, country=country)

# Step 4: feature-flagged factory. Every caller in the monolith uses this.
def pricing_for_request(request) -> PricingService:
    if flags.enabled("pricing.new_service", user=request.user):
        return NewPricing(client=pricing_client)
    return OldPricing()

Notice what this buys you: you can roll back instantly. If the new service misbehaves at 10% traffic, flip the flag off. No deploy, no panic. The monolith still has OldImpl — it is the safety net. You only delete it after the new service has been at 100% for long enough that you trust it.

Anti-Corruption Layer

This is a Domain-Driven Design term from Eric Evans. The point is to refuse to let legacy concepts leak into your new bounded context. If you do not draw this line, the “new” service ends up modeling the same things the monolith did, with the same names, the same nullability quirks, and the same surprising behaviors — and you have built nothing.

An ACL typically has three responsibilities:

• Schema translation. Map customers.cust_typ_cd = 'PR' to Customer.kind = "premium". The new service never sees the cryptic code.
• Identity mapping. The monolith uses integer IDs assigned by an Oracle sequence. The new service uses ULIDs. The ACL keeps a translation table.
• Behavior reconciliation. The monolith treats null as “not yet decided”; the new service models that as an explicit state. The ACL converts.

# Anti-corruption layer between new OrderService and legacy DB.
class LegacyOrderTranslator:
    def to_domain(self, row: dict) -> Order:
        return Order(
            id=ULID.from_legacy(row["ord_id"]),
            status=self._status(row["st_cd"], row["cancel_dt"]),
            total=Money.cents(row["tot_amt_cents"], row["curr_cd"]),
            customer_id=ULID.from_legacy(row["cust_id"]),
        )

    def _status(self, code: str, cancel_dt) -> OrderStatus:
        if cancel_dt is not None:    return OrderStatus.CANCELLED
        if code == "P":               return OrderStatus.PENDING
        if code == "S":               return OrderStatus.SHIPPED
        if code == "D":               return OrderStatus.DELIVERED
        raise ValueError(f"unknown legacy status {code}")

The translator is ugly. That is the entire point. The ugliness is contained in one file, with tests. Everything downstream consumes Order objects with sensible names. When the legacy system finally goes away, you delete this file and lose nothing.

Decomposition Heuristics

Bounded contexts come from Domain-Driven Design and are the most reliable lens. If two parts of the monolith use the same word to mean different things — order, customer, product — you have found a context boundary. Force-fitting them into one shared model is what produced the mess in the first place.

Data Migration

Splitting a database is where most migrations either succeed or quietly become a distributed monolith. The cardinal rule: each service owns its data, and no other service touches that data except through the owner’s API or events. The moment a second service starts reading the “orders” tables directly, you have lost. You can never change the schema again without coordinating across services.

The four phases of splitting a table

1. Shared database, separate schemas. Both services hit the same physical DB but use different schemas. Forces ownership clarity without yet paying the operational cost.
2. Dual write. When the monolith updates the table, it also calls the new service’s API. Or vice versa. Useful for a brief window; dangerous as a steady state because it has no atomicity guarantee.
3. Change data capture (CDC). Run Debezium or similar against the monolith’s WAL/binlog. Stream every change to Kafka. The new service consumes the stream and builds its own copy of the data. No application code in the monolith changes.
4. Cutover. Switch writes from the monolith to the new service. The CDC stream now flows the other way (or stops). Eventually the monolith’s tables are decommissioned.

Outbox pattern for safe dual writes

A naive dual write — write to the DB, then call the other service — can leave the two systems out of sync if the call fails after the DB commit. The outbox pattern solves this with a single local transaction that writes both the business row and the “message I owe to the other service.” A separate process publishes from the outbox.

-- The outbox lives in the same database as the business data,
-- so a single ACID transaction covers both writes.

CREATE TABLE outbox (
    id            BIGSERIAL PRIMARY KEY,
    aggregate_id  TEXT      NOT NULL,
    event_type    TEXT      NOT NULL,
    payload       JSONB     NOT NULL,
    created_at    TIMESTAMPTZ NOT NULL DEFAULT now(),
    published_at  TIMESTAMPTZ
);

-- Application code writes business + outbox in one transaction.
BEGIN;
  UPDATE orders SET status = 'shipped' WHERE id = 12345;
  INSERT INTO outbox (aggregate_id, event_type, payload)
  VALUES ('order:12345', 'OrderShipped',
          '{"order_id":12345,"shipped_at":"2026-05-12T18:00:00Z"}');
COMMIT;

A small relay process polls the outbox (or, better, watches the WAL via Debezium) and publishes each row to Kafka. Once published, it stamps published_at. If the relay crashes, it resumes — consumers must be idempotent on event ID. This pattern is the backbone of every reliable monolith-to-services migration that involves event-driven communication.

Debezium CDC connector example

// Debezium connector for PostgreSQL: stream every change in the
// monolith’s public.orders table to a Kafka topic.
{
  "name": "monolith-orders-cdc",
  "config": {
    "connector.class": "io.debezium.connector.postgresql.PostgresConnector",
    "plugin.name": "pgoutput",
    "database.hostname": "monolith-db.internal",
    "database.port": "5432",
    "database.user": "debezium",
    "database.password": "${file:/secrets/cdc.pw}",
    "database.dbname": "shop",
    "topic.prefix": "monolith",
    "table.include.list": "public.orders,public.order_items",
    "snapshot.mode": "initial",        // backfill once, then tail WAL
    "publication.autocreate.mode": "filtered",
    "heartbeat.interval.ms": "10000",    // keep WAL position fresh
    "key.converter": "org.apache.kafka.connect.json.JsonConverter",
    "value.converter": "org.apache.kafka.connect.json.JsonConverter"
  }
}

The new orders-service consumes monolith.public.orders and builds its own materialized view. While dual reads are running, you can shadow read — query both, compare, log diffs. After a few weeks of zero diffs you flip writes to the new service and reverse the CDC direction so the monolith stays in sync long enough for read paths to migrate.

Common Anti-Patterns

Most migrations fail in predictable ways. Recognize them early, refuse them by name.

Real-World Examples

Amazon (~2002). Jeff Bezos’s famous internal mandate: every team must expose its data and functionality through service interfaces, no other communication is permitted, all interfaces must be designed to be externalizable. The migration took years and was driven by a coordination problem — teams could not deploy independently of each other against a shared monolith. The result was the architecture that eventually became AWS.

Etsy. Famously stayed on a PHP monolith well into eight-figure user counts. They invested in continuous deployment (50+ deploys a day to one codebase), staff-plus engineering on infrastructure, and eventually carved out a small number of strategic services. The lesson: a disciplined monolith with great deploy infrastructure beats undisciplined microservices.

Shopify. Runs a Ruby on Rails “modular monolith” — one repo, one process, but with strict internal package boundaries enforced by tooling (Packwerk). They have extracted services where it was justified (storefront rendering, payments) but the core stays modular monolith. This is the direction most successful large Rails shops have gone.

Uber. Went from monolith to roughly 2,200 microservices, then publicly acknowledged they had over-decomposed. They consolidated some areas back into “domain-oriented microservice architecture” — bigger services aligned to business domains rather than tiny ones aligned to entities. The lesson: more services is not better; right-sized services aligned to teams is better.

Stack Overflow. Runs a tiny number of servers and a small number of large services. Their write-up of running “100 million page views per month on nine on-prem servers” is mandatory reading before any architect proposes 50 microservices. Often, you do not have the problem you think you have.

Best Practices

In practice, most teams should not migrate — they should clean up. The teams that should migrate should plan for years, not quarters, and should expect that the boundaries they draw on day one will be wrong. That is fine. Strangler fig, branch by abstraction, and anti-corruption layers exist precisely so you can change your mind safely.