DBRaven
Pattern · messaging

Change Data Capture via WAL

established

Summary

Stream database changes in real-time by reading the write-ahead log, enabling downstream consumers to react to inserts, updates, and deletes without polling or dual writes.

Problem

Applications need to propagate database changes to caches, search indexes, or event streams without dual writes, polling, or tight coupling to business logic.

Description

PostgreSQL's logical replication decodes the WAL into a stream of row-level change events. A CDC tool (Debezium, pglogical, Postgres logical replication slot) captures this stream and forwards events to message queues, search indexes, caches, or analytical stores.

CDC solves the dual-write problem: instead of writing to both the database and a secondary system (with risk of partial failure), the primary write to the database is treated as the single source of truth, and all secondaries are derived from the log.

Tradeoffs

Data consistency
+0.8

Exact change sequence preserved; no missed updates

Operational complexity
-0.6

Replication slots and CDC tooling require operational expertise

Coupling
+0.8

Downstream systems decouple from application write paths

Disk risk
-0.5

Lagging consumers retain WAL on disk; can exhaust storage

When to use

Multiple downstream systems need to react to database changes

CDC provides a single pipeline instead of N separate dual-write integrations

Data consistency between primary store and derived stores is required

CDC preserves the exact change sequence from the primary

Polling-based sync is causing excessive read load

CDC is event-driven: no polling overhead

When not to use

Downstream systems can tolerate significant lag (minutes to hours)

Scheduled batch ETL is simpler for latency-tolerant cases

Database does not support logical replication

Requires PostgreSQL 10+ with logical replication enabled

Operational Requirements

mandatory

Monitor replication slot lag continuously

Lagging slots hold WAL indefinitely; set slot_inactive_timeout or drop inactive slots

mandatory

Set wal_level=logical in postgresql.conf

Default wal_level=replica is insufficient for logical decoding

recommended

Size disk with WAL retention headroom for consumer lag

Assume consumer can be down for hours; provision disk accordingly

Characteristics

Scales on
write
Implementation complexitymedium
Operational complexityhigh
Scaling ceilingLimited by WAL generation rate and replication slot lag. Slow consumers cause WAL retention buildup, which can exhaust disk space. Must monitor replication slot lag rigorously.

Technologies

Canonical

postgresqldebezium

Alternatives

pglogicalaws dms

Relationships

Evolves from

polling sync

Evolves to

event sourcingcqrs

Complements

read replicaoutbox pattern

Basis

Well-established pattern; operational complexity is real and must be communicated

Related Architecture Knowledge

Outbound: this entity affects

Informs GenerationPattern
event sourcing
Grounded

Write-ahead log CDC is the technical substrate that enables event-driven downstream architectures. Understanding how WAL CDC works and its operational characteristics directly informs generation of event-driven patterns such as CQRS, event sourcing, and streaming pipelines built on database change capture.

Tradeoffs

  • ·WAL CDC adds load to the primary: each slot must track WAL independently
  • ·Dropped replication slot can cause disk exhaustion in hours under heavy write load
  • ·Schema evolution is a significant operational challenge for long-running CDC streams
Full relationship →

Inbound: affects this entity

SupportsTechnology
kafka
Grounded

Kafka is the standard downstream target for WAL-based CDC pipelines: Debezium captures database WAL records and publishes them to Kafka topics, which downstream consumers process to maintain derived data stores, caches, and event-driven services.

Tradeoffs

  • ·Debezium replication slot holds WAL until consumed: disconnected Debezium can fill primary disk
  • ·CDC events are row-level operations: application-level event semantics require transformation in a stream processor
  • ·Ordering guarantees are per-partition only: cross-table ordering requires careful partition key strategy
Full relationship →

Used In Architecture Scenarios

Analytics Data Platformhigh

Analytics Pipeline

An OLAP-oriented analytics architecture that ingests operational changes from PostgreSQL via WAL-based CDC into Kafka, then routes them to a columnar analytics store (ClickHouse or Snowflake) for product analytics, business intelligence, and operational reporting. The CQRS separation ensures analytical queries never degrade transactional write performance, and materialized views provide pre-aggregated query acceleration for the most expensive analytical patterns.

Audit and Compliance Platformhigh

Financial Ledger

An append-only audit log architecture for capturing system actions: user operations, data access events, configuration changes, and financial operations: with cryptographic integrity chaining, immutable storage, and dual-path query serving. PostgreSQL stores the authoritative append-only event log in time-partitioned tables; ClickHouse serves historical aggregate queries and retention analytics; Kafka streams audit events in real time to SIEM integrations and security dashboards; Redis caches hot audit query results for compliance-facing read paths. No record is ever updated or deleted: only inserts are permitted. Each record includes a hash of the previous record, forming a tamper-evident chain verifiable without external tooling.

Event-Driven Analytics Pipelinehigh

Event-Driven System

A streaming architecture that captures database changes via WAL-based CDC, publishes them to an event stream (Kafka), and routes them to analytics consumers. Decouples the write path from the read path while maintaining a durable, replayable event log.

Healthcare Records Platformexpert

Financial Ledger

An electronic health record (EHR) architecture built around strict auditability, HIPAA compliance, and append-only correctness. Clinical records are mutable by design (amendments, addenda) but corrections must be explicitly attributed, not silently overwritten. Event sourcing provides a reconstructable audit log; PostgreSQL row-level security enforces patient-level access control at the database layer; Kafka streams HL7 FHIR events to downstream clinical systems. The architecture must support breach detection, access auditing, and state reconstruction at any historical point: not just current state retrieval.

IoT Telemetry Ingestion Platformhigh

Write-Heavy Application

A high-rate device telemetry ingestion architecture designed for millions of devices emitting metrics at 1–60 second intervals. Kafka absorbs device writes as an ingestion buffer, decoupling device-facing ingest endpoints from the storage write path so that downstream storage pressure never propagates back to devices. TimescaleDB provides time-series storage with automatic chunk partitioning by time range, native compression, and continuous aggregate views for rollup queries. ClickHouse serves as the OLAP layer for device fleet analytics queries. Redis caches last-known device state (current readings per device) for real-time alerting queries that must not scan historical storage. Backpressure on the Kafka consumer side prevents storage write throughput from being overwhelmed by burst ingestion events from device reconnect storms.

Observability Platformhigh

Analytics Pipeline

A metrics, logs, and traces ingestion and query platform built to absorb the telemetry output of a production system fleet: including the telemetry volume spikes that accompany the incidents the platform is meant to detect. ClickHouse stores metrics data with automatic time-based rollup via continuous materialized views; TimescaleDB provides complementary time-series storage for high-cardinality alert evaluation; Kafka buffers the ingestion stream against downstream write pressure, decoupling ingest acceptance rate from storage write throughput; Elasticsearch serves log full-text search and structured field filtering; Redis caches dashboard query results and active alert state for sub-100ms alert evaluation latency. The alert engine evaluates threshold and anomaly rules against pre-computed materialized views, not raw data, to bound alert evaluation cost independent of ingestion volume.

Search-Heavy Content Platformhigh

Search-Heavy Application

A content platform architecture centered on Elasticsearch for full-text search, faceted navigation, and ranked results, with PostgreSQL as the transactional source of truth and Redis for session management and hot content caching. WAL-based CDC maintains index freshness by streaming PostgreSQL changes into Elasticsearch asynchronously. The core tension is between search index freshness, query performance, and index maintenance cost under high write volume.

Streaming Media Platformhigh

Event-Driven System

A video and audio streaming architecture where content ingestion triggers an async multi-variant transcoding pipeline, CDN delivery handles 95%+ of playback traffic, and Cassandra absorbs the write volume of per-user viewing history. Kafka decouples upload events from transcoding workers; MinIO stores raw and encoded assets; Redis maintains playback session state and view counters. The architecture must handle upload spikes without blocking delivery, and cache cold starts without cascading database load.

Write-Heavy Transactional Platformhigh

Write-Heavy Application

A high-volume transactional write architecture anchored on PostgreSQL, where write throughput, durability guarantees, and audit completeness must coexist. The outbox pattern ensures reliable event publishing to Kafka without two-phase commit, and WAL-based CDC provides a durable change log that can reconstruct system state. Connection pooling via PgBouncer bounds connection overhead at the database layer.