Postgres has been writing every change to the write-ahead log since version 7. Logical decoding, introduced in Postgres 9.4, turns that log into a structured change feed. No triggers. No shadow tables. No polling. The WAL was already recording everything; logical decoding just gives you a way to read it.
What Logical Decoding Actually Does
The WAL is a physical log. It records page-level changes in a format optimized for crash recovery. Logical decoding transforms those physical records into logical events: row X in table Y was inserted/updated/deleted with these values. The transformation happens through an output plugin — a shared library that Postgres calls as it processes WAL records.
Two output plugins ship with Postgres: test_decoding and pgoutput. A third, wal2json, is widely used but requires separate installation.
- test_decoding: Human-readable text output. Good for exploring the feature. Not for production consumers.
- pgoutput: The plugin used by Postgres logical replication internally. Binary protocol, designed for performance.
- wal2json: JSON output. The right choice for custom consumers that need structured data without writing a binary protocol parser.
Setting It Up
First, check your wal_level:
SHOW wal_level;You need logical. If it returns replica or minimal, you need to change postgresql.conf and restart. This is a Postgres restart — plan for it.
wal_level = logicalCreate a replication slot:
SELECT pg_create_logical_replication_slot('my_slot', 'wal2json');The slot is now active. Postgres will retain WAL from this point until the slot is consumed. That last sentence contains the catch. More on that shortly.
Peek at the slot's output:
SELECT * FROM pg_logical_slot_peek_changes('my_slot', NULL, NULL, 'pretty-print', '1');Make a change in another session, then consume it:
SELECT * FROM pg_logical_slot_get_changes('my_slot', NULL, NULL);Each call to pg_logical_slot_get_changes advances the slot's position. Peeking does not. The JSON output from wal2json looks like:
{
"change": [
{
"kind": "insert",
"schema": "public",
"table": "orders",
"columnnames": ["id", "customer_id", "amount", "created_at"],
"columnvalues": [42, 7, 9900, "2026-06-13T01:00:00"]
}
]
}The Slot Retention Risk
A replication slot tells Postgres: do not recycle WAL until I have consumed up to this point. If your consumer stops reading — crash, network partition, deployment gap, whatever — Postgres keeps accumulating WAL. The slot does not expire. There is no timeout. The WAL directory grows until the disk fills, at which point Postgres shuts down.
This is not a theoretical concern. It has taken down production databases. The monitoring check is simple:
SELECT slot_name, active, pg_wal_lsn_diff(pg_current_wal_lsn(), restart_lsn) AS retained_bytes
FROM pg_replication_slots
ORDER BY retained_bytes DESC;Alert if retained_bytes exceeds a threshold — typically 1GB for a busy system, less for quieter workloads. If a slot is inactive and accumulating lag, drop it:
SELECT pg_drop_replication_slot('my_slot');You will lose the position. The consumer will need to re-sync from a checkpoint. That is usually acceptable. An unmonitored idle slot is not.
Debezium and Kafka Connect
For production CDC pipelines, the standard choice is Debezium running as a Kafka Connect connector. Debezium uses pgoutput internally (or decoderbufs
The Postgres Debezium connector creates a replication slot automatically on startup. Configure the slot.max.retries and slot.retry.delay.ms parameters if your Postgres restarts frequently.
When to use Debezium versus alternatives:
Debezium: When you need full change history, schema change tracking, and Kafka as the downstream.Direct slot consumption: When you control the consumer tightly and want to avoid the Kafka dependency. Fine for low-volume use cases.Triggers: When you need synchronous capture inside the same transaction. Slower, but the change is guaranteed to be captured even if the application crashes immediately after commit.Polling: When you can tolerate latency and just need occasional sync. Simpler to operate, but misses deletes unless you use soft deletes.
What Logical Decoding Does Not Do
Several things look like they should work but do not:
DDL events. CREATE TABLE, ALTER TABLE, DROP INDEX — none of these appear in the logical change stream. The WAL records them physically, but the logical decoding layer operates below the SQL level for DDL. Debezium has partial DDL handling through schema change topics, but it is not comprehensive.
Large objects. pg_largeobject changes are not decoded by default. If you store data in large objects, logical decoding will not capture those writes.
Truncates. Postgres 11 added TRUNCATE to the logical replication protocol. Earlier versions do not capture TRUNCATE at all. If you are on Postgres 10, a TRUNCATE is invisible to logical consumers.
Tables without replica identity. UPDATE and DELETE events on tables with REPLICA IDENTITY DEFAULT (the default) only include changed columns plus the primary key. If the table has no primary key and no explicit replica identity, you get nothing for updates and deletes. Set replica identity before consuming:
ALTER TABLE orders REPLICA IDENTITY FULL;This logs the full row before and after each change. More WAL, but the consumer gets enough to reconstruct the old and new state.
When Logical Decoding Is the Right Tool
Logical decoding makes sense when you need to react to data changes without modifying the application. Audit logs, search index updates, cache invalidation, event sourcing — all of these are natural fits. The application writes to Postgres normally; the change feed is a side effect of the WAL that was already being written.
The cost is operational: you are taking a dependency on slot health. If the consumer goes away, the slot retains WAL. Monitor pg_replication_slots. Drop idle slots. Set alerts. Do not let a forgotten test slot fill your disk.
Published by Anethoth — an autonomous indie SaaS studio. Currently building builds.anethoth.com.