Prerequisites

What CDC Reads

Every durable database already maintains an ordered, committed record of every change it has made. It exists for crash recovery and replication. Change data capture consumes that same log as an event source.

Log-Based Versus Query-Based

Before log-based capture became widely available, systems polled tables for changed rows. The approaches differ substantially in completeness.

What a Change Event Contains

{
    "source": {
        "connector": "postgresql",
        "db": "commerce",
        "schema": "public",
        "table": "orders",
        "lsn": 28419374,
        "txId": 4471902,
        "commitTs": "2026-09-24T06:52:11.482Z"
    },
    "op": "u",
    "before": {
        "order_id": "order-7734",
        "status": "confirmed",
        "total": 249900,
        "updated_at": "2026-09-24T06:40:00Z"
    },
    "after": {
        "order_id": "order-7734",
        "status": "shipped",
        "total": 249900,
        "updated_at": "2026-09-24T06:52:11Z"
    }
}

Snapshot and Streaming

A new consumer needs existing data, not only future changes. CDC connectors therefore operate in two phases.

The Coupling Problem

This is the central design tension in CDC. Publishing row changes exposes your internal schema as a public contract, whether or not you intended it.

CDC Combined With the Outbox

The two patterns are complementary rather than competing. The outbox provides the contract; CDC provides the delivery.

BEGIN;

UPDATE orders
SET status     = 'shipped',
    updated_at = CURRENT_TIMESTAMP
WHERE order_id = :order_id;

INSERT INTO outbox (aggregate_type, aggregate_id, event_type, payload)
VALUES (
    'order',
    :order_id,
    'OrderShipped',
    :domain_event_payload
);

COMMIT;
-- A CDC connector on the outbox table publishes the event,
-- while the orders table remains entirely private

Deletes and Tombstones

Deletes require special handling because a compacted topic must know the key is gone, not merely that its last value was a delete event.

{
    "key": { "order_id": "order-7734" },
    "value": {
        "op": "d",
        "before": { "order_id": "order-7734", "status": "cancelled" },
        "after": null
    }
}

{
    "key": { "order_id": "order-7734" },
    "value": null
}

Ordering and Transactions

The log preserves commit order, but that ordering survives only if the downstream topology respects it.

{
    "status": "BEGIN",
    "id": "4471902",
    "ts_ms": 1790007131482
}

{
    "status": "END",
    "id": "4471902",
    "event_count": 4,
    "data_collections": [
        { "data_collection": "public.orders", "event_count": 1 },
        { "data_collection": "public.order_items", "event_count": 3 }
    ]
}

Operational Constraints

-- Monitor replication slot lag before it becomes an incident
SELECT slot_name,
       active,
       pg_size_pretty(
           pg_wal_lsn_diff(pg_current_wal_lsn(), restart_lsn)
       ) AS retained_wal
FROM pg_replication_slots
ORDER BY pg_wal_lsn_diff(pg_current_wal_lsn(), restart_lsn) DESC;

Where CDC Is Used

Zero-Downtime Migration

CDC Versus Outbox

Failure Modes

Monitoring

Verification

describe("change data capture", function () {
    it("emits an event for every operation type", async function () {
        await source.insert("orders", { order_id: "o-1", status: "placed" });
        await source.update("orders", "o-1", { status: "shipped" });
        await source.delete("orders", "o-1");

        const events = await stream.drain("orders");

        expect(events.map(e => e.op)).toEqual(["c", "u", "d"]);
    });

    it("includes before and after images on update", async function () {
        await source.insert("orders", { order_id: "o-2", total: 100 });
        await source.update("orders", "o-2", { total: 200 });

        const update = (await stream.drain("orders")).find(e => e.op === "u");

        expect(update.before.total).toBe(100);
        expect(update.after.total).toBe(200);
    });

    it("resumes from the recorded position after restart", async function () {
        await source.insert("orders", { order_id: "o-3" });
        await connector.stop();
        await source.insert("orders", { order_id: "o-4" });
        await connector.start();

        const events = await stream.drain("orders");
        const ids = events.map(e => e.after?.order_id);

        expect(ids).toContain("o-4");
    });

    it("preserves per-row ordering under concurrent writes", async function () {
        await Promise.all([
            source.update("orders", "o-5", { status: "confirmed" }),
            source.update("orders", "o-5", { status: "shipped" })
        ]);

        const sequence = (await stream.drain("orders"))
            .filter(e => e.after?.order_id === "o-5")
            .map(e => e.after.status);

        expect(sequence).toEqual(["confirmed", "shipped"]);
    });
});

Common Design Mistakes

System Design Interview Discussion

Design Checklist

Knowledge Check

Summary

Change data capture turns a database's write-ahead log into an event stream. Because that log already contains every committed change in order, and the database depends on its completeness for recovery, CDC inherits reliability rather than adding a new mechanism for it.

Log-based capture is materially stronger than polling, which misses deletes and intermediate states silently. A new consumer begins with a snapshot and then streams from the exact log position at which the snapshot was taken.

The central drawback is coupling. Publishing row changes exposes the internal schema as a contract, so migrations become breaking changes and the database stops being private. CDC also cannot express intent, since it reports what changed rather than why.

The strongest arrangement for cross-service events combines both patterns: write a deliberate domain event to an outbox table in the business transaction, and let a CDC connector publish it. That yields atomicity, low latency, no polling relay, and a contract you designed rather than one you leaked.