CONCEPT Cited by 1 source
Postgres logical replication slot¶
Definition¶
A Postgres logical replication slot is a row in the
pg_replication_slots
catalog on a Postgres primary that represents a persistent
cursor into the WAL from the perspective of one logical-
replication subscriber. It carries two pieces of state:
restart_lsn— the oldest WAL position the slot still requires (for replaying decoded changes the subscriber has not yet confirmed).confirmed_flush_lsn— the most recent WAL position the subscriber has confirmed it has received and flushed.
As long as the slot exists, Postgres must retain WAL back to
restart_lsn — WAL segments cannot be recycled or archived
off if any slot still needs them. The slot's state is advanced
only when a subscriber connects, receives events, and
acknowledges them. A subscriber that is offline or lagging
pins WAL on the primary indefinitely; a sufficiently lagging
subscriber can fill the primary's WAL volume.
Why the slot is primary-local¶
The slot is a catalog object, not a WAL-stream object. It
lives in the primary's pg_replication_slots table. Pre-
Postgres-17, its state never rode along in WAL, so
standbys had no authoritative copy — promotion of a standby
meant the slot was gone and any subscriber using it had to
re-snapshot. Postgres 17's
failover slots change this by serialising slot metadata
into WAL, but keep the slot fundamentally primary-driven:
only the primary accepts subscriber connections that advance
it.
The WAL-pinning property¶
Sam Lambert canonicalises the property verbatim:
"The logical replication slot is a durable, primary-local object that carries two pieces of state: the oldest WAL the slot requires (
restart_lsn) and the most recent position the subscriber has confirmed (confirmed_flush_lsn). The presence of that slot pins WAL on the primary until the CDC client advances." (Source: sources/2026-04-21-planetscale-postgres-high-availability-with-cdc)
Two operational consequences:
- Lagging subscriber → WAL accumulation. Expected behaviour. Postgres trusts the slot; WAL grows until the subscriber catches up or the slot is dropped.
- Dropped slot → subscriber must re-snapshot. There is no out-of-band resume point. If the slot goes, the subscriber cannot tell Postgres "resume me from LSN X" because LSN retention was bounded by that slot.
Decoding via pgoutput¶
The slot names a logical-decoding output plugin
(most commonly pgoutput
for built-in logical replication;
wal2json
and decoderbufs
for Debezium integrations). The plugin decodes physical WAL
records into per-row change events (insert/update/delete with
column values), filtered by the slot's associated publication
(the set of replicated tables). See
concepts/logical-replication.
Contrast with MySQL binlog subscription¶
MySQL has no slot concept. A CDC consumer persists its own
GTID position; any MySQL server
with matching binlog retention can serve as a resume point,
and log_replica_updates=ON replicas re-emit transactions
so replication is a property of every server, not a
contract between the primary and one subscriber.
Seen in¶
- sources/2026-04-21-planetscale-postgres-high-availability-with-cdc
— canonical wiki introduction of the logical replication
slot as the primary-local object that couples HA to CDC.
Sam Lambert (PlanetScale CEO, 2025-09-12) positions the slot
as the structural root of Postgres's HA-vs-CDC trade-off:
"the progress of the slowest slot determines how far the
system can move without manual intervention." Discloses
restart_lsn+confirmed_flush_lsnwire, WAL-pinning property, primary-local catalog placement, and the asymmetry with MySQL binlog CDC (action log vs state log + primary- local progress catalog).