PostgreSQL CDC: how it works

PostgreSQL change data capture reads row changes from the write-ahead log (WAL) through logical decoding. A replication slot remembers how far a consumer has read, an output plugin turns WAL records into a readable stream, and a client such as Debezium publishes each insert, update and delete as an event. It needs wal_level set to logical, one slot per connector, and a plan for three failures: WAL growth, duplicate events and missing before-images.

This post covers the PostgreSQL side. For the wider choice of CDC methods and tools, see change data capture services. For running connectors in production, see Debezium consulting.

• wal_level = logical. Debezium's PostgreSQL documentation requires it, and the setting is applied at server start, so plan a restart.
• An output plugin. pgoutput is built in from PostgreSQL 10 and needs no extra libraries. decoderbufs is a community plugin that must be installed. Managed services such as Amazon RDS and Cloud SQL require pgoutput to be named explicitly.
• A replication role for the connector, with only the privileges it needs.
• One slot per connector. A slot streams the changes of a single database, and only one receiver can read it at a time, so give each connector its own slot name.
• A publication. pgoutput reads through publications. Debezium can create one for all tables, which is its default, or a filtered one for the tables you name.
• Primary keys. Update and delete events identify the row by its replica identity. See below.

Debezium alternatives compared covers the vendors in more detail.

A slot keeps WAL until its consumer confirms it. PostgreSQL's documentation warns that neither required WAL nor required catalog rows can be removed as long as a slot needs them, that this can consume significant storage, and that in extreme cases it can force a shutdown to prevent transaction ID wraparound. A slot that is no longer needed should be dropped.

Two things make it worse. First, max_slot_wal_keep_size defaults to -1, which lets slots retain unlimited WAL, so set a limit that protects the primary. A slot that falls further behind than the limit can no longer be used to continue, and the connector then needs a new snapshot. PostgreSQL 18 adds idle_replication_slot_timeout, which is disabled by default (PostgreSQL 18 release notes). Second, slots work per database. If the connector watches a quiet table while other databases or tables on the server are busy, Debezium has nothing to confirm and the slot lags. Debezium's remedy is a heartbeat: set heartbeat.interval.ms, and use heartbeat.action.query to write a row so the position advances.

Alert on retained WAL per slot, pg_wal_lsn_diff(pg_current_wal_lsn(), restart_lsn), and on a confirmed_flush_lsn that stops advancing while the primary keeps writing. A restart_lsn that trails a rising confirmed_flush_lsn is normal: Debezium notes that PostgreSQL reclaims WAL in batches. If you use a heartbeat table, add it to the publication unless the publication is FOR ALL TABLES. A worked case is in the replication slot WAL use case.

The slot position is persisted only at checkpoint, so after a crash the slot can return to an earlier position and send recent changes again. Debezium also commits offsets periodically, so an outage can replay events that consumers have already seen. Neither is a fault. Treat delivery as at least once and make consumers idempotent on the primary key, for example by upserting on key and ignoring an event older than the stored version.

What an update or delete event contains depends on the table's replica identity. With the default, the previous values include only the primary key, and a table with no primary key emits only create events. REPLICA IDENTITY FULL sends the previous values of every column, at the cost of larger WAL records. Large unchanged TOAST values are left out of update events under the default identity, and Debezium substitutes a placeholder string that is set with unavailable.value.placeholder. Decide per table what consumers need, and add primary keys before you start.

A new connector takes a snapshot first. The default snapshot.mode is initial, and incremental snapshots let you backfill a table added later without stopping streaming, with the read-only variant needing PostgreSQL 13 or later.

Slots live on the primary. From PostgreSQL 17, failover slots let a standby carry a copy, and Debezium can continue reading from the slot on the new primary once slot.failover is enabled and the standby's slot is listed in synchronized_standby_slots. Without that, a promoted standby generally has no slot, so a failover means recreating the slot and snapshotting again. Rehearse it before it happens.

AceMQ's Debezium support engineers handle slot and WAL incidents, snapshots and connector restarts, and our PostgreSQL support covers the database side. The CDC design work is described on the change data capture page.

• PostgreSQL 18 documentation: logical decoding concepts
• PostgreSQL 18 documentation: replication settings
• Debezium documentation: PostgreSQL connector (3.7)
• Debezium documentation: Debezium Server (3.7)

Documentation read on 31 October 2026. Check the pages for your PostgreSQL and Debezium versions before changing a production system.