Change Data Capture via WAL
establishedSummary
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
Exact change sequence preserved; no missed updates
Replication slots and CDC tooling require operational expertise
Downstream systems decouple from application write paths
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
Monitor replication slot lag continuously
Lagging slots hold WAL indefinitely; set slot_inactive_timeout or drop inactive slots
Set wal_level=logical in postgresql.conf
Default wal_level=replica is insufficient for logical decoding
Size disk with WAL retention headroom for consumer lag
Assume consumer can be down for hours; provision disk accordingly
Characteristics
Technologies
Canonical
Alternatives
Relationships
Evolves from
Evolves to
Complements
Basis
Well-established pattern; operational complexity is real and must be communicated
Related Architecture Knowledge
Outbound: this entity affects
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
Inbound: affects this entity
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
Used In Architecture Scenarios
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.
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 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.
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.
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.
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 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.
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 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.