Skip to content

CONCEPT Cited by 1 source

Logical replication

Definition

Logical replication is a replication mode in which the primary database emits a stream of row-level change events (insert / update / delete with primary-key and column values), instead of replicating opaque storage-layer artefacts like physical pages or WAL byte-ranges ("physical replication"). Consumers of the stream can materialise the changes into any compatible target — another database of the same or different kind, a Kafka topic, a search index, a data lake, an event consumer — because the payload is semantic rather than storage-format-specific.

In Postgres, logical replication is enabled by setting wal_level=logical and creating a publication (the set of tables being replicated) and a replication slot (a persistent cursor into the WAL that prevents the WAL from being recycled until the consumer has acknowledged consumption through that point).

Why it matters for system design

Logical replication is the substrate under almost every CDC pipeline in the Postgres ecosystem. Debezium's Postgres source connector subscribes to a logical replication slot and emits the row-level changes as Kafka records. That lets one Postgres feed any number of heterogeneous downstream systems without a custom trigger / polling pipeline per consumer.

Contrast with physical streaming replication (the WAL- byte-stream mode Postgres uses for hot standbys): physical replication is simpler and faster but requires binary-compatible replicas, cannot transform records in flight, and cannot feed non-Postgres destinations.

Requirements on Postgres

From Datadog's 2025-11-04 retrospective, enabling logical replication in service of a Debezium CDC pipeline requires:

  • wal_level=logical (instance-wide setting).
  • Postgres users with the correct replication permissions.
  • Replication publishers (publications) defining which tables / operations to replicate.
  • Replication slots (one per consumer) to pin WAL progress.
  • Heartbeat tables — a Debezium-specific pattern where a dummy table gets written periodically so the slot can advance LSN during quiet periods; without it, an idle slot prevents WAL recycling indefinitely (Postgres pins WAL until the slowest active slot catches up).

(Source: sources/2025-11-04-datadog-replication-redefined-multi-tenant-cdc-platform)

Relationship to WAL

Logical replication is derived from the same Postgres WAL stream that physical replication uses, but decoded into row-level change events via the logical-decoding plugin. The WAL is therefore load-bearing in two roles on a CDC-enabled Postgres:

  1. Durability of local transactions (the original purpose).
  2. Carrier of the change stream for all downstream logical consumers.

This dual role makes logical replication extra-sensitive to WAL- retention configuration: slow or stalled consumers pin WAL and can exhaust disk space on the primary.

Seen in

Last updated · 200 distilled / 1,178 read