How does a Postgres logical replication slot retain WAL?

A replication slot is a server-side promise: Postgres will keep every WAL record a consumer might still need until that consumer confirms it has processed it. CDC tools and logical subscribers depend on this because they decode changes from WAL. If WAL were recycled while a consumer was disconnected, the consumer would lose changes with no way to recover them. The slot is stored on the server and persists whether or not anything is connected to it.

Each logical slot tracks two positions:

  • confirmed_flush_lsn is the point up to which the consumer has acknowledged receiving and durably handling changes.
  • restart_lsn is the oldest WAL position decoding would need to resume. It is often behind confirmed_flush_lsn because a transaction that was still open when the confirmed changes were committed must be decoded from its beginning.
 oldest WAL on disk                                        current insert LSN
  |                                                                    |
  [seg][seg][seg][seg][seg][seg][seg][seg][seg][seg][seg][seg][seg][seg]
             ^             ^                       ^
             |             |                       |
     slot A restart_lsn    slot A confirmed_flush  slot B restart_lsn
             |
  <-- recyclable --|-------------- must be retained ------------------->

At checkpoint time, the server cannot remove or recycle any segment at or after the oldest restart_lsn across all slots. One stalled slot pins WAL for the entire cluster, regardless of how current the other slots are.

Logical slots also hold back catalog_xmin. Decoding needs old versions of system catalog rows to interpret historical changes under the schema that applied when they were written. For that reason, vacuum cannot remove dead catalog tuples newer than this horizon. On databases with heavy DDL or temporary table churn, catalogs such as pg_class and pg_attribute can bloat. Watching WAL disk usage will not show this cost.

 pg_wal/ WAL stream (oldest -> newest)
 oldest segment                                         current insert LSN
 |                                                                       |
 +-----+-----+-----+-----+-----+-----+-----+-----+-----+-----+-----+-----+
 | 01  | 02  | 03  | 04  | 05  | 06  | 07  | 08  | 09  | 10  | 11  | 12  |
 +-----+-----+-----+-----+-----+-----+-----+-----+-----+-----+-----+-----+
              ^                 ^                 ^           ^
              |                 |                 |           |
        slot A             slot A            slot B       slot B
        restart_lsn        confirmed_flush   restart_lsn  confirmed_flush
 <-recyclable|<--------- retained: at/after oldest restart_lsn ---------->

  +-----------------------+          +-----------------------+
  | slot A: CDC consumer  |          | slot B: subscriber    |
  | disconnected, stalled |          | connected, current    |
  +-----------+-----------+          +-----------+-----------+
              | catalog_xmin                     | catalog_xmin
              +----------------+-----------------+
                               | oldest catalog_xmin applies
                               v
        +---------------------------------------------+
        | vacuum cannot remove dead pg_catalog rows   |
        | still visible to the oldest catalog_xmin    |
        | -> catalog bloat; pg_wal size won't show it |
        +---------------------------------------------+

The oldest restart_lsn across all slots (here, stalled slot A) sets the WAL recycling boundary for the whole cluster, and the oldest catalog_xmin blocks vacuum from removing dead system catalog rows.

Why do replication slots become inactive or stop advancing?

A slot does not know whether its consumer is coming back. It holds WAL until the consumer confirms progress, and nothing else will move it. In practice, slots stall for a few recurring reasons:

Failure mode What pg_replication_slots shows Why WAL keeps accumulating
CDC consumer crashed, paused or scaled to zero active = false No client is connected to advance the slot
Subscriber dropped, slot left on the publisher active = false, indefinitely The slot outlives the system that used it
Slot from a one-off migration or test active = false, unfamiliar name Nobody remembers it exists
Consumer connected but not acknowledging active = true, confirmed_flush_lsn static The client reads changes but never reports them as flushed
Long-running transaction on the primary active = true, restart_lsn lagging Decoding must keep WAL from the start of the oldest in-progress transaction

The fourth row is the most misleading. A green "connected" check passes while retention grows. Common causes are a client bug that skips feedback messages, or a consumer whose tracked tables see no writes while the rest of the cluster generates WAL.

The underlying problem is coupling. With unbounded retention, the primary's availability depends on every downstream consumer staying healthy. One abandoned slot can fill the WAL volume, and a full WAL disk stops writes for every application on that database.

Treat this as a shared ownership problem. Any team that runs CDC pipelines, logical subscribers or migration tooling against a primary owns slot hygiene, along with the team operating the database.

How do you measure retained WAL per slot?

The number that matters is how far each slot's restart_lsn trails the current write position. Postgres cannot recycle any WAL segment at or after the oldest restart_lsn, so the gap between the two is the disk that slot is holding. Query pg_replication_slots and compute pg_wal_lsn_diff(pg_current_wal_lsn(), restart_lsn) for each row. Wrap it in pg_size_pretty() for humans, but alert on the raw bytes. Run this on the primary, because pg_current_wal_lsn() errors on a standby.

For logical slots, also compute the same difference against confirmed_flush_lsn. That is the point the consumer has acknowledged. A small confirmed lag paired with a large restart_lsn gap usually means the consumer is keeping up, but a long-running transaction is pinning restart_lsn back, since decoding has to restart from that transaction's start. A large confirmed lag means the consumer itself is behind. confirmed_flush_lsn is null for physical slots, so filter on slot_type.

Read the remaining columns together:

  • active and active_pid show whether a walsender currently holds the slot. An inactive slot with growing retention is the classic abandoned consumer.
  • wal_status, where your server exposes it, reports whether the required WAL is still guaranteed. A value of lost means the slot can no longer be used.
  • A null restart_lsn means the slot has reserved no WAL yet.

Column sets differ across Postgres versions, and managed offerings may restrict functions or add their own views. Check every query against the exact environment before you build alerts on it.

-- Run on the PRIMARY: pg_current_wal_lsn() raises an error during recovery.
-- Assumes Postgres 13+ for wal_status; drop that column on older servers.
-- Validate column availability on your exact version / managed offering.
SELECT
  slot_name,
  slot_type,                 -- 'physical' or 'logical'
  database,                  -- null for physical slots
  active,                    -- true while a walsender holds the slot
  active_pid,                -- walsender PID, null when inactive
  wal_status,                -- e.g. 'lost' means the slot is no longer usable

  -- WAL this slot prevents from being recycled. Alert on the raw bytes.
  -- Null if restart_lsn is null (slot has not reserved WAL yet).
  pg_wal_lsn_diff(pg_current_wal_lsn(), restart_lsn) AS retained_bytes,
  pg_size_pretty(
    pg_wal_lsn_diff(pg_current_wal_lsn(), restart_lsn)
  ) AS retained_pretty,

  -- How far the logical consumer's acknowledged position trails.
  -- confirmed_flush_lsn is null for physical slots, so only compute it for logical.
  CASE WHEN slot_type = 'logical'
       THEN pg_wal_lsn_diff(pg_current_wal_lsn(), confirmed_flush_lsn)
  END AS confirmed_lag_bytes
FROM pg_replication_slots
-- Largest retainers first; inactive slots near the top are likely abandoned.
ORDER BY retained_bytes DESC NULLS LAST;

A query against pg_replication_slots that reports the WAL bytes each slot retains via restart_lsn, plus the confirmed_flush_lsn lag for logical slots, alongside slot_type, active, active_pid and wal_status.

Is it really the slot? Ruling out other causes of WAL growth

A logical slot is the usual suspect, but Postgres keeps WAL for several independent reasons. It only recycles a segment once every retention mechanism has released it. Removing a slot does nothing if something else is still holding the oldest segment.

Archiving that is failing

When archive_mode is on, a segment cannot be recycled until archive_command reports success for it. A broken command, such as an expired credential or a full destination, silently pins everything from the first failure onward. Query pg_stat_archiver and compare last_failed_time with last_archived_time. If the most recent failure is newer than the most recent success and failed_count keeps rising, the archiver is the cause. A growing number of .ready files under pg_wal/archive_status confirms it.

A fixed retention floor

wal_keep_size keeps a fixed amount of WAL regardless of consumers. Run SHOW wal_keep_size. A large value accounts for growth up to that size, but it never causes unbounded growth.

Physical slots

Run SELECT slot_name, active, restart_lsn FROM pg_replication_slots WHERE slot_type = 'physical' and compute retained bytes with pg_wal_lsn_diff(pg_current_wal_lsn(), restart_lsn). A decommissioned standby whose slot still exists behaves exactly like an abandoned logical slot.

Retention cause Typical symptom Where to check
Failing archive_command Steady growth, archive errors in server log pg_stat_archiver, pg_wal/archive_status
wal_keep_size Large but flat WAL volume SHOW wal_keep_size
Physical slot Growth tied to a stopped or removed standby pg_replication_slots (physical)
Logical slot Growth tied to a stalled consumer pg_replication_slots (logical)
-- 1. Archiver: is archive_command failing and pinning segments?
SELECT archived_count,
       failed_count,
       last_archived_wal,
       last_archived_time,
       last_failed_wal,
       last_failed_time,
       -- true when the most recent failure is newer than the last success
       coalesce(last_failed_time > last_archived_time, false) AS archiver_stuck
FROM pg_stat_archiver;

-- Count segments still waiting to be archived (.ready files, PG 12+)
SELECT count(*) AS ready_segments
FROM pg_ls_archive_statusdir()
WHERE name LIKE '%.ready';

-- 2. Fixed retention floor: bounded, never unbounded growth
SHOW wal_keep_size;

-- 3 and 4. Slots: WAL retained by each physical and logical slot
SELECT slot_name,
       slot_type,
       active,
       restart_lsn,
       pg_size_pretty(
         pg_wal_lsn_diff(pg_current_wal_lsn(), restart_lsn)
       ) AS retained_wal
FROM pg_replication_slots
WHERE restart_lsn IS NOT NULL
ORDER BY pg_wal_lsn_diff(pg_current_wal_lsn(), restart_lsn) DESC;

-- Compare against total WAL on disk to see which cause explains the volume
SELECT pg_size_pretty(sum(size)) AS pg_wal_total
FROM pg_ls_waldir();

Run these diagnostic queries on the primary to rule each WAL retention cause in or out: a failing archiver, the wal_keep_size floor, and physical or logical slots. Comparing their retained sizes against total pg_wal usage shows which cause accounts for the growth.

How should you alert on replication slot WAL growth?

Disk usage percentage tells you the volume is filling. It doesn't tell you why, and by the time it fires, most of your headroom is gone. Alert on two slot-level signals instead: retained bytes per slot (the distance between the current WAL position and the slot's restart_lsn) and inactivity duration (how long active has been false). Disk percentage stays as a backstop, not the primary signal.

Sizing thresholds against write rate

Derive thresholds from the time you need to respond, not from round numbers.

Illustrative estimate. Assume these inputs:

  • 200 GB free on the WAL volume
  • About 2 GB/hour of WAL during normal traffic
  • Up to 10 GB/hour during nightly bulk loads

If the retained-bytes alert fires at 50 GB, 150 GB of headroom remains. That leaves about 75 hours at the normal rate, but only about 15 hours during a bulk load. If your on-call can reliably act within a few hours, 50 GB is reasonable. If a slot can stall overnight unnoticed, size the threshold against the spike rate, not the average.

The trade-off

Thresholds that are too tight fire during planned maintenance, consumer redeploys, and bulk loads. On-call learns to ignore them. Thresholds that are too loose look fine until a spike in WAL generation compresses the response window from days to hours.

Two practices reduce the noise without losing coverage:

  • Use a short grace period on inactivity. A few minutes covers routine consumer restarts.
  • Add a separate time-to-full estimate. Divide free space by the recent WAL generation rate, so spikes are caught even when retained bytes are still modest.

Why per-slot alerts save time

A disk alert starts an investigation. A per-slot alert names the slot, and the slot name maps to a specific consumer and its owning team. On-call skips the triage covered in the previous section and goes straight to the stalled connector or subscriber.

-- Per-slot WAL retention and inactivity check, run on the primary.
-- Thresholds mirror the illustrative estimate: 50 GB retained bytes,
-- 5-minute grace period on inactivity to absorb routine consumer restarts.
-- inactive_since requires PostgreSQL 17+; wal_status requires 13+.
WITH slots AS (
  SELECT
    slot_name,
    slot_type,
    database,
    active,
    wal_status,
    -- Bytes of WAL this slot forces the server to keep.
    pg_wal_lsn_diff(pg_current_wal_lsn(), restart_lsn) AS retained_bytes,
    -- How long the slot has had no connected consumer (NULL while active).
    now() - inactive_since AS inactive_for
  FROM pg_replication_slots
  WHERE restart_lsn IS NOT NULL
)
SELECT
  slot_name,          -- maps to the owning consumer and team
  slot_type,
  database,
  active,
  wal_status,
  pg_size_pretty(retained_bytes) AS retained,
  inactive_for,
  -- Emit one reason per slot so the page names what to fix.
  CASE
    WHEN retained_bytes > 50::bigint * 1024 * 1024 * 1024
      THEN 'retained_bytes_over_50GB'
    WHEN NOT active AND inactive_for > interval '5 minutes'
      THEN 'inactive_over_grace_period'
  END AS alert_reason
FROM slots
WHERE retained_bytes > 50::bigint * 1024 * 1024 * 1024
   OR (NOT active AND inactive_for > interval '5 minutes')
ORDER BY retained_bytes DESC;

A query against pg_replication_slots that returns only slots exceeding a 50 GB retained-bytes threshold or inactive past a 5-minute grace period, naming each slot so the alert points on-call at the owning consumer (inactive_since needs PostgreSQL 17 or later).

When should you use max_slot_wal_keep_size, and when should you avoid it?

max_slot_wal_keep_size sets an upper bound on how much WAL replication slots can force the server to keep. If a slot falls further behind than the cap, Postgres may remove the WAL it still needs and invalidate the slot. An invalidated slot cannot be resumed. The consumer must be rebuilt, which for logical replication usually means a fresh initial copy of the published tables. The setting trades disk safety for data continuity. Availability, the default, and exactly when invalidation happens differ between releases, so check the documentation for the version you run.

Approach Disk risk Data-continuity risk Operational cost
Unbounded slot High: one stalled consumer can fill the WAL volume and stop the primary Low: the slot never loses its position Low until an incident, then severe
Capped slot Bounded by the cap High: the slot is invalidated after a long outage A full downstream resync after each invalidation
Alerting plus manual intervention Medium: depends on response time Low, if on-call acts before the disk fills Ongoing on-call load and runbooks

To choose a cap, start from the free space on the WAL volume and subtract headroom for normal WAL volume and bursts. Then estimate how much WAL you generate during the longest consumer outage you are willing to tolerate. The cap should sit between these two numbers. If the tolerated outage produces more WAL than the disk can hold, the cap cannot protect you without also invalidating the slot, so you need more disk or a faster response.

Avoid a cap when a resync is worse than the risk to disk. Multi-terabyte tables, slow initial copies, and downstream systems that cannot easily reload are all cases where invalidation turns a recoverable stall into days of rework. In those cases, rely on early alerts and enough disk headroom to ride out a stall.

What should you do when a slot is filling the WAL disk?

Decide whether the consumer can catch up

Check whether the slot is active in pg_replication_slots and whether its confirmed position is still moving. A live consumer that is slowly draining a backlog may only need time and disk headroom. A consumer that is crashed, misconfigured, or decommissioned will never release the WAL, so waiting only brings the disk closer to full.

If the consumer cannot recover, drop the slot with pg_drop_replication_slot. If a walsender still holds the slot, terminate that backend first. The drop is irreversible. A new slot starts at the current WAL position, not the old one, so the consumer needs a fresh initial snapshot or a full resync. Tell the owners of downstream systems before you drop it.

If the disk is nearly or completely full

Never delete files from the WAL directory by hand. Postgres may still need those segments for crash recovery, and removing them can leave the cluster unable to start without data loss. Free space safely instead. Remove unrelated files on the same volume, such as old logs or dumps, or extend the volume. Either step may be needed just to get a stopped server running again.

Then deal with the offending slot and run a CHECKPOINT. Confirm that the WAL directory shrinks as segments are recycled or removed.

Extending the volume buys time but does not fix the stalled consumer. Also, a slot's held-back catalog_xmin may have let system catalogs bloat. Check catalog bloat after the drop and follow up with vacuum.

How can you prevent slot incidents and reduce their engineering cost?

Prevention is cheaper than that cleanup, because most of these incidents come from slots that nobody remembers creating.

Ownership and naming

Give every slot a name that identifies its consumer, its environment and its owning team. Postgres only stores the slot name, so a name like cdc_orders_prod_payments tells whoever is on call who to contact before dropping it. Keep a short registry of slots, owners and expected consumers. That way an audit can find slots with no matching consumer.

Teardown and storage

Make slot removal part of decommissioning. When a CDC connector, test subscriber or migration tool is retired, its teardown should drop the slot. If the tool created the slot, the tool or its pipeline should drop it. Teams often delete a consumer and forget its slot, and that slot keeps holding WAL with nothing reading it.

Put WAL on a volume sized for the longest consumer outage you are willing to tolerate. Alert on free space on that volume as well as per-slot lag.

Periodic audits

Run an audit on a schedule, weekly for example. The query reads pg_replication_slots and, for each slot, returns:

  • slot_name, slot_type and database
  • active
  • retained bytes, computed as pg_wal_lsn_diff(pg_current_wal_lsn(), restart_lsn)

Sort the results with inactive slots first, then by retained bytes in descending order. Compare each slot name against the registry.

Why this lowers cost

An audit takes minutes and happens during working hours. An incident-driven cleanup is different: an engineer is paged, has to rule out other causes of WAL growth while the disk fills, and makes the decision to drop a slot under pressure. Dropping the slot then often forces the downstream consumer to do a full resync. That resync can take days of engineering time and can lead to data reconciliation work.

How OneEnv can help

Disclosure: OneEnv is the product behind this blog.

OneEnv (oneenv.io) is a workspace-based governance platform for the things services share — environment variables, database structure, API routes and validation rules. A change to a shared value is staged on a branch, reviewed once, and then every affected service explicitly approves or rejects it before it goes live, so you can see who a change touches before it ships instead of finding out in production.

Applied to postgres replication slot wal growth, this is where it helps:

Saves time

  • Every service that inherits a shared value is listed in one place, so nobody searches repos and chats to find out who is affected.
  • One review per branch replaces coordinating each team separately; each service still keeps its own approve/reject.
  • Changing a route's URL or method automatically notifies the services that consume it — no hunting through repos for callers.

Saves cost

  • Fewer production incidents and rollbacks caused by a shared value, route or column changing under a consumer unannounced.
  • Less duplicated configuration to maintain: one shared definition inherited by many services.
  • Consumers learn about a breaking change at review time rather than from production errors.
  • OneEnv has a free plan (1 workspace, unlimited services and members, full governance), so trying it costs nothing.

These are qualitative benefits, not measured results — how much you save depends on how many services share the value.

Want to try it? Start at oneenv.io.