Replication Slot
A replication slot is a PostgreSQL object that tracks how far a consumer has read the write-ahead log and retains WAL until the consumer confirms it.
What Is a Replication Slot?
Replication slots are PostgreSQL objects that track how far a consumer has read the write-ahead log (WAL), the log every change is written to before it reaches data files. A slot guarantees that the server keeps every WAL segment the consumer has not yet confirmed, so a standby or CDC client can disconnect and resume without missing changes.
Slots survive crashes, but a slot's position is flushed to disk only at checkpoint, so after a crash the server can resend changes the consumer already received.
How Replication Slots Work
Each slot stores WAL positions, or LSNs (log sequence numbers, byte offsets into the WAL), that the consumer advances by reporting what it has flushed. The pg_replication_slots view exposes them:
restart_lsn– the oldest WAL position the slot still needs. No segment from this point forward can be recycled.confirmed_flush_lsn(logical slots) – the last position the consumer acknowledged as written downstream. Streaming resumes after it.catalog_xmin(logical slots) – the oldest transaction ID whose catalog rows the slot needs. VACUUM cannot remove dead catalog rows newer than it.
restart_lsn can trail confirmed_flush_lsn because decoding restarts from the oldest transaction still open at the confirmed point, so one long-running transaction on the source holds back WAL even when the consumer is caught up.
Types of Replication Slots
- Physical slots serve streaming-replication standbys, which attach through
primary_slot_name. They retain raw WAL with no decoding state, replacing the fixed buffer ofwal_keep_size. - Logical slots serve logical replication subscribers and change data capture tools such as Debezium. Each belongs to one database and is bound to an output plugin (
pgoutput,wal2json,test_decoding) that turns WAL into row-level change events through logical decoding. - Temporary slots of either kind live only for the creating session and are dropped on disconnect.
pg_basebackupuses one by default.
How to Monitor Replication Slot Lag
Slot lag is the byte distance between the current WAL write position and a slot's restart_lsn or confirmed_flush_lsn. Run on the primary:
SELECT slot_name, active, wal_status,
pg_size_pretty(pg_current_wal_lsn() - restart_lsn) AS retained_wal,
pg_size_pretty(pg_current_wal_lsn() - confirmed_flush_lsn) AS consumer_lag,
pg_size_pretty(safe_wal_size) AS safe_wal_size
FROM pg_replication_slots;- Retained WAL is disk held on the primary; consumer lag is how far the destination trails the source.
activeandinactive_since(PostgreSQL 17+) show whether a consumer is connected, and since when it has not been.wal_statusmoves fromreservedtoextended,unreservedandlostas retention grows;safe_wal_sizeis the headroom before invalidation.
Action is due when retained WAL grows across checkpoints on an inactive slot, when wal_status leaves reserved, or when retained WAL nears free disk. Thresholds depend on each server's WAL rate and headroom. More queries: creating, monitoring and dropping slots in PostgreSQL.
Common Replication Slot Problems
- Disk growth. A stalled slot holds WAL until
pg_walfills its volume, and PostgreSQL shuts down when it cannot write WAL. See preventing WAL growth on AWS RDS. - Inactive slots. Slots left by a retired connector retain WAL and hold
catalog_xmin, causing catalog bloat and transaction ID wraparound pressure. - Quiet databases. Writes outside the publication, including managed-service internal writes, advance WAL without producing events, so a consumer that only confirms on events never advances the slot. See unbounded WAL growth on idle RDS databases.
- Failover. Before PostgreSQL 17, logical slots weren't synced to standbys, so promotion forced a resnapshot. PostgreSQL 17 logical failover slots sync them to standbys via
sync_replication_slots.
Replication Slot Best Practices
- Create one slot per consumer, named after it. A slot accepts one connection at a time.
- Set
max_slot_wal_keep_sizeto cap WAL retention below available disk. The trade-off: a slot over the cap is invalidated and its consumer must resnapshot. - Set
idle_replication_slot_timeout(PostgreSQL 18+, off by default) above any planned consumer pause. - Alert on retained WAL and long-running transactions;
idle_in_transaction_session_timeoutbounds the latter. - Drop slots when retiring a consumer:
pg_terminate_backendon its WAL sender, thenpg_drop_replication_slot. - Advance slots on quiet databases with heartbeat writes to a published table, such as Debezium's
heartbeat.action.querysetting. The guide to capturing CDC from Postgres without breaking production covers sizing and upgrades.
Frequently asked questions
What happens when a consumer disconnects for hours?
A disconnected consumer's slot stays in place, and the primary retains all WAL from its restart_lsn. On reconnect, the consumer resumes after confirmed_flush_lsn with no lost changes, unless retained WAL exceeded max_slot_wal_keep_size or the slot passed idle_replication_slot_timeout, which invalidate it.
How many slots can one database have?
PostgreSQL caps slots per server, not per database, with max_replication_slots, which defaults to 10 and requires a restart to change. Each connected consumer also uses a WAL sender process, so max_wal_senders must cover all concurrent consumers.
Does dropping a slot lose data?
Dropping a slot deletes no table data. It discards the consumer's position and releases retained WAL, so unconfirmed changes can no longer be streamed. A CDC pipeline whose slot was dropped needs a new slot and a fresh snapshot or backfill to restore consistency.
Do managed Postgres services limit slots?
Managed services cap Postgres replication slots through parameters. Amazon RDS and Aurora require rds.logical_replication = 1 in a custom parameter group plus a reboot. Cloud SQL requires the cloudsql.logical_decoding flag, defaults max_replication_slots to 10, and raises the ceiling with instance memory.