How does a logical replication slot cause Postgres WAL growth?

A logical replication slot is a promise from the primary to a specific consumer: "I will keep every WAL record you might still need until you tell me you have it." The server keeps that promise whether or not anyone is connected to the slot.

Each slot tracks two positions in the WAL stream:

  • restart_lsn: the oldest WAL location the logical decoder may still need. Decoding has to begin far enough back to reassemble transactions that were open at the consumer's last acknowledged point. As a result, restart_lsn usually trails the acknowledged position.
  • confirmed_flush_lsn: the position the consumer has acknowledged as durably received. The decoder will not send changes before this point again.

PostgreSQL computes the oldest restart_lsn across all slots and refuses to recycle or remove any WAL segment from that point forward. It applies this rule to active slots and inactive slots alike. A slot whose consumer disappeared last week holds WAL exactly as firmly as a healthy one.

 older WAL                                                newer WAL
 ──────────────────────────────────────────────────────────────────▶
 [recyclable] │◀──────────── retained, cannot be recycled ─────────▶│
              │                                                     │
          restart_lsn          confirmed_flush_lsn          current write
         (oldest slot)          (consumer acked)              position

Teams use slots for change data capture connectors and for native logical replication to subscribers. The slot is what makes these consumers reliable: a consumer can reconnect after downtime and resume without losing changes. If you run a primary with CDC connectors or logical subscribers attached, the retained region in the diagram is disk space that you are responsible for monitoring.

 older WAL ───────────────────────────────────────────────────▶ newer WAL
 ┌───────┬───────┬───────┬───────┬───────┬───────┬───────┬───────┬───────┐
 │ seg 1 │ seg 2 │ seg 3 │ seg 4 │ seg 5 │ seg 6 │ seg 7 │ seg 8 │ seg 9 │
 └───────┴───────┴───────┴───────┴───────┴───────┴───────┴───────┴───────┘
 slot_b (inactive: consumer disconnected, still holds WAL)
           R══════════C
           │ slot_a (active: CDC connector acknowledging changes)
           │                       R══════════════C
           │                                current write position ─▶ W
           ▼                                                          ▼
 recyclable│◀─────── retained: cannot be recycled or removed ────────▶│

 R = restart_lsn          oldest WAL the decoder may still need
 C = confirmed_flush_lsn  position the consumer has acknowledged
 W = current write position on the primary

 Retention floor = oldest restart_lsn across ALL slots (here: slot_b),
 whether the slot is active or not.

Each logical slot tracks a restart_lsn and a confirmed_flush_lsn, and PostgreSQL retains every WAL segment from the oldest restart_lsn across all slots, including inactive ones, up to the current write position.

How does slot-based WAL retention work, step by step?

The retention behaviour comes from a short loop that runs continuously on the primary:

  1. Writes produce WAL. Every committed change, in every database on the cluster, is appended to the WAL as fixed-size segment files in pg_wal.
  2. A walsender decodes WAL for the slot. When a consumer connects to a logical slot, a walsender process reads WAL from the slot's position. It passes the changes through the slot's output plugin, such as pgoutput for native logical replication, and streams the decoded changes to the consumer.
  3. The consumer reports progress. The consumer periodically sends feedback saying which position it has durably flushed. The server records this as confirmed_flush_lsn.
  4. The server advances restart_lsn when it can. Once no transaction that is still needed for decoding started before a given point, the slot's restart_lsn can move forward. An old open transaction or a consumer that never confirms keeps it where it is.
  5. Checkpoints decide what WAL can go. At each checkpoint, the server works out the oldest WAL position still required. It takes into account the oldest restart_lsn across all slots, wal_keep_size, and any segments not yet archived. Segments older than that point are removed or recycled, and everything newer stays on disk.
  6. An optional cap overrides the slot. If max_slot_wal_keep_size is set, a slot that would require more WAL than the cap is invalidated, and its WAL becomes eligible for removal.

Physical slots used by streaming standbys follow the same rule through their restart_lsn, so a disconnected standby with a slot pins WAL in the same way.

Each step corresponds to something you can observe. Steps 3 and 4 appear as the two LSN columns in pg_replication_slots. Step 4's blocker shows up in pg_stat_activity. Step 5's outcome is the size of the WAL volume. Step 6 shows up as wal_status. The rest of this article uses those observation points.

Who should use slot monitoring and WAL retention limits?

You need the practices in this article if any of the following applies:

  • You run a primary with logical replication slots. This includes CDC connectors that stream changes to queues, search indexes, or warehouses, and native logical subscribers. Every such slot can pin WAL.
  • You run streaming standbys through physical slots. The consumer is different, but the retention risk is the same when a standby goes away.
  • You are on call for a shared cluster. When several applications share one primary, a single stalled consumer that belongs to one team can stop writes for all of them. The on-call engineer needs a way to see which slot is responsible and who owns it.
  • Your WAL lives on a small or shared volume. Less headroom means less time between a consumer stalling and the primary stopping.
  • You operate platform or database tooling that creates slots on behalf of other teams. You own the inventory, the naming convention, and the cleanup process.

If SELECT count(*) FROM pg_replication_slots; returns zero and nothing in your environment creates slots, slot-driven WAL growth does not apply to you yet. Add the monitoring when the first consumer arrives, not after the first full disk.

Why do replication slots grow without bound?

Retention has no built-in limit. The slot holds WAL until its consumer confirms it, and nothing in the default configuration forces that confirmation to happen.

Common causes:

  • Abandoned slot. A consumer is decommissioned or migrated, but nobody drops its slot. The slot stays inactive and pins WAL indefinitely.
  • Down or crash-looping connector. The connector reconnects, fails before acknowledging progress, and repeats. The slot may briefly look active, but its position does not move.
  • Consumer lag during write bursts. Bulk loads or backfills produce WAL faster than the consumer can decode and apply it.
  • Long-running transactions. Decoding has to start from before the oldest transaction that was still open. An idle-in-transaction session can hold restart_lsn back even while confirmed_flush_lsn advances.
  • Low traffic on the slot's database. WAL is cluster-wide, but a slot only receives changes for its own database. If that database is quiet while other databases on the cluster are busy, the consumer has nothing to acknowledge and its position barely moves.
Cause Symptom in pg_replication_slots
Abandoned slot active = false, restart_lsn fixed
Crash-looping connector active flaps, confirmed_flush_lsn stuck
Burst lag Both LSNs advancing, but the gap to the current WAL position widens
Long transaction confirmed_flush_lsn moves, restart_lsn stuck
Low-traffic database Slot active, LSNs advance rarely while other databases generate WAL

When the WAL volume fills, Postgres cannot write WAL and the primary shuts down. One dead consumer therefore causes an outage for every application on the cluster.

Adding disk only buys time. The growth rate stays the same. Retained WAL also stacks with other sources of retention. WAL kept for the slot is not removed even after it has been archived, and a failing archive command or a wal_keep_size setting adds its own retained WAL on top.

How do you find the slot that is filling the disk with pg_replication_slots?

Start with the catalog view itself. Selecting slot_name, plugin, slot_type, database, active and active_pid from pg_replication_slots shows every slot, which decoding plugin it uses, and whether a process is attached. A slot with active = false and a null active_pid has no consumer. It is the usual suspect, but not the only one.

Add two computed columns, wrapping each in pg_size_pretty() so the output is readable:

  • Retained WAL: pg_wal_lsn_diff(pg_current_wal_lsn(), restart_lsn). This is the disk cost. Postgres cannot recycle any segment newer than restart_lsn.
  • Consumer lag: pg_wal_lsn_diff(pg_current_wal_lsn(), confirmed_flush_lsn). This measures how far behind the consumer's acknowledgements are. confirmed_flush_lsn is only populated for logical slots.

Run these on the primary, because pg_current_wal_lsn() is not available during recovery.

The two numbers can diverge. The decoder must reread WAL from the start of the oldest transaction that was still open when the consumer last confirmed. Suppose a session holds a write transaction open for hours, or sits idle in transaction after writing. The consumer keeps confirming other commits, so lag stays small, but restart_lsn stays pinned and retained WAL keeps climbing.

To find that session, query pg_stat_activity for rows where xact_start is old. Select pid, state, backend_xid, now() - xact_start and query, ordered by xact_start.

Take several readings before acting. A slot that shows gigabytes retained right after a bulk load may be draining normally. A slot whose numbers rise steadily across readings is the one filling the disk.

-- Run on the primary: pg_current_wal_lsn() errors during recovery.
-- Retained WAL = disk cost; lag = how far behind the consumer's acks are.
SELECT slot_name,
       plugin,
       slot_type,
       database,
       active,
       active_pid,
       pg_size_pretty(pg_wal_lsn_diff(pg_current_wal_lsn(), restart_lsn))
         AS retained_wal,
       -- confirmed_flush_lsn is NULL for physical slots
       pg_size_pretty(pg_wal_lsn_diff(pg_current_wal_lsn(), confirmed_flush_lsn))
         AS consumer_lag
FROM pg_replication_slots
ORDER BY pg_wal_lsn_diff(pg_current_wal_lsn(), restart_lsn) DESC NULLS LAST;

-- High retained_wal with low consumer_lag often means an old open
-- transaction is pinning restart_lsn. Find the oldest transactions:
SELECT pid,
       state,
       backend_xid,
       now() - xact_start AS xact_age,
       left(query, 80)    AS query
FROM pg_stat_activity
WHERE xact_start IS NOT NULL
  AND now() - xact_start > interval '15 minutes'  -- example threshold; adjust to your workload
ORDER BY xact_start;

-- One reading can mislead: repeat the slot query a few times
-- (e.g. with \watch 60 in psql) and look for steady growth.

Queries that rank replication slots by retained WAL alongside consumer lag, then list long-open transactions in pg_stat_activity that can pin restart_lsn.

How does max_slot_wal_keep_size cap WAL retention?

By default, max_slot_wal_keep_size is -1, which means slots may retain unlimited WAL. A stalled consumer can hold WAL until the volume fills and the primary stops accepting writes. Setting a positive value caps how much WAL a slot can pin. When a slot falls further behind than the cap, PostgreSQL may remove the WAL it needs and invalidate the slot. You trade a broken replication stream for a primary that stays up. That trade is usually correct, because recreating a slot and resyncing a consumer is cheaper than a full disk on the primary.

Two columns in pg_replication_slots show how close each slot is to that limit:

  • wal_status moves from reserved (within max_wal_size) to extended (retained beyond it, still safe), then unreserved (at risk), then lost (invalidated).
  • safe_wal_size is how many bytes can still be written before the slot is at risk. It is null when the cap is unlimited.

Check the documentation for your PostgreSQL version to confirm these columns exist.

Sizing the cap (illustrative estimate)

  • Assumed WAL generation rate: 2 GB/hour
  • Assumed tolerated consumer outage: 8 hours, which comes to 16 GB
  • Assumed free space on the WAL volume: 100 GB

Add 50% headroom to the 16 GB outage window and you get max_slot_wal_keep_size = 24GB. That is well below 100 GB, which leaves room for normal WAL up to max_wal_size and for bursts. The setting takes effect on a configuration reload.

-- Cap how much WAL any replication slot may retain.
-- 24GB = assumed 16 GB outage window (2 GB/hour x 8 hours) + 50% headroom.
-- These are illustrative assumptions, not measurements.
ALTER SYSTEM SET max_slot_wal_keep_size = '24GB';

-- The parameter takes effect on reload; no restart is needed.
SELECT pg_reload_conf();

-- Confirm the active value.
SHOW max_slot_wal_keep_size;

-- Run on the primary: see how close each slot is to invalidation.
-- wal_status: reserved -> extended -> unreserved -> lost
-- safe_wal_size: bytes that can still be written before the slot is at risk
--                (NULL when max_slot_wal_keep_size = -1).
-- Confirm these columns exist in the docs for your PostgreSQL version.
SELECT
    slot_name,
    slot_type,
    active,
    wal_status,
    pg_size_pretty(safe_wal_size) AS safe_wal_remaining,
    pg_size_pretty(
        pg_wal_lsn_diff(pg_current_wal_lsn(), restart_lsn)
    ) AS retained_wal
FROM pg_replication_slots
ORDER BY safe_wal_size ASC NULLS LAST;

Sets a 24GB max_slot_wal_keep_size from the illustrative estimate, reloads the configuration, and queries pg_replication_slots to show each slot's wal_status, remaining safe_wal_size, and currently retained WAL.

When should you avoid a WAL retention ceiling, and what are the alternatives?

A ceiling trades consumer continuity for primary availability. When max_slot_wal_keep_size invalidates a slot, the consumer cannot resume from its last confirmed position. It needs a new slot and an initial snapshot or full resync. On a large database that can take hours. Changes made between invalidation and the new snapshot can also leave a gap that the downstream system has to reconcile. Unlimited retention, the default of -1, keeps every consumer's position intact. The cost is that one stalled consumer can fill the disk and stop the primary.

Sizing the ceiling is hard in both directions. If it is too low, slots get invalidated during a routine maintenance window or a short consumer outage, so you pay resync costs for incidents that would have recovered on their own. If it is too high on a shared or small volume, the ceiling only triggers after other files have already run out of space, so it protects almost nothing.

Option Risk to primary Recovery cost when a consumer stalls Engineering effort
Unlimited retention + strict alerting High if alerts are missed or on-call is slow Low: consumer resumes where it stopped Medium: alerting, runbooks, on-call
Ceiling with accepted resync cost Low High: resnapshot plus possible downstream gap Low to medium: sizing, resync tooling
Larger or dedicated WAL volume Lower, and other files can't fill it Low, if the outage fits Medium: storage provisioning, cost
Prompt slot cleanup Low for abandoned slots only None for slots nobody uses Low: inventory and ownership

Decide per workload. A CDC pipeline that feeds billing may justify unlimited retention on a dedicated volume. An analytics replica that can be rebuilt overnight is a good fit for a tight ceiling. Prompt cleanup of abandoned slots helps in every case.

What should you alert on before the disk fills?

Four signals cover most failure modes:

  • Retained bytes per slot: pg_wal_lsn_diff(pg_current_wal_lsn(), restart_lsn) from pg_replication_slots.
  • Inactive slots: active = false. A slot with no connected consumer retains WAL indefinitely.
  • Stalled progress: a confirmed_flush_lsn that has not changed across a window, such as 15 minutes. A connected consumer can still be stuck.
  • Free space on the WAL volume: read from the host or volume metrics, because SQL cannot see the filesystem.

A scrapeable query selects slot_name, slot_type, active, the retained-bytes expression, and confirmed_flush_lsn as a numeric offset. Your metrics system then stores each slot as a time series and computes change over time itself.

Alert on the trend, not only the threshold

A fixed threshold such as "slot retains 50 GB" fires too late on a fast write workload and too early on a quiet one. Derive the growth rate and alert on projected time-to-full: free space divided by retained-bytes growth per hour. Here is an illustrative estimate with assumed inputs. With 200 GB free and retention growing 20 GB per hour, on-call has about ten hours. They can investigate during working hours instead of being paged at 95% usage.

Separate a stuck consumer from a pinned restart_lsn

Add the age of the oldest open transaction from pg_stat_activity (now() - xact_start). Logical decoding cannot advance restart_lsn past a transaction that is still running. If confirmed_flush_lsn is moving but restart_lsn is not, the likely cause is a long transaction on the primary, not the consumer. Each case needs a different owner to fix it.

Catching growth hours ahead usually means restarting a consumer or ending one idle session. Missing it can mean dropping the slot, re-snapshotting the downstream system, and reconciling the data afterward.

-- One row per slot, flat numeric columns for a metrics scraper.
-- Run on the primary: pg_current_wal_lsn() errors during recovery.
WITH oldest_xact AS (
  -- Longest-running open transaction. It can pin restart_lsn for logical slots.
  SELECT COALESCE(EXTRACT(EPOCH FROM max(now() - xact_start)), 0)
           AS oldest_xact_age_seconds
  FROM pg_stat_activity
  WHERE xact_start IS NOT NULL
)
SELECT
  s.slot_name,
  s.slot_type,                              -- 'physical' or 'logical'
  s.active::int AS active,                  -- 0 means no consumer is connected
  -- WAL bytes this slot forces the server to keep
  pg_wal_lsn_diff(pg_current_wal_lsn(), s.restart_lsn) AS retained_bytes,
  -- LSNs as byte offsets so the metrics system can compute deltas.
  -- A flat restart_lsn alongside a moving confirmed_flush_lsn
  -- points to a long transaction, not the consumer.
  pg_wal_lsn_diff(s.restart_lsn, '0/0') AS restart_lsn_bytes,
  -- NULL for physical slots, which have no confirmed_flush_lsn
  pg_wal_lsn_diff(s.confirmed_flush_lsn, '0/0') AS confirmed_flush_lsn_bytes,
  o.oldest_xact_age_seconds
FROM pg_replication_slots s
CROSS JOIN oldest_xact o;

A scrapeable query that reports retained WAL bytes, activity, and restart and confirmed-flush positions as numeric offsets for each slot, plus the age of the oldest open transaction, so the metrics system can compute growth rates and tell a stalled consumer apart from a pinned restart_lsn.

How do you safely remediate a runaway slot and keep slots healthy?

Remediation runbook

Work through these steps in order. Each one is cheaper and more reversible than the next.

  1. Identify the owner. Map the slot name and its plugin to a team, service, or connector. Do not change anything until someone who knows the consumer is involved.
  2. Restart or unblock the consumer if it is still needed. A crashed connector, a stuck downstream write, or a revoked credential is often the whole cause. Once the consumer confirms progress again, the server can recycle retained WAL at the next checkpoint.
  3. Check pg_stat_activity for long-running or idle-in-transaction sessions. Logical decoding cannot move its restart point past the oldest transaction still in progress. A forgotten session can hold WAL even when the consumer is healthy. Ending that session is usually low-risk.
  4. Drop the slot with pg_drop_replication_slot only after the owner accepts that the consumer must be resynced from a fresh snapshot. Dropping cannot be undone. The changes the slot was holding are gone for that consumer. If you drop it without a resync plan, an outage turns into silent data divergence downstream.

Never delete files from the WAL directory by hand. The server still expects them, and removing them can leave the cluster unable to recover.

Ongoing hygiene

  • Name slots so the owner is obvious, for example by including the team and service in the name.
  • Add slot cleanup to decommissioning runbooks, so removing a consumer also removes its slot.
  • Review slots on a schedule and question any slot without a known owner.

On quiet databases, the confirmed position can stall because no relevant changes arrive to acknowledge. Use the connector's or consumer's heartbeat setting, or periodic heartbeat writes, to keep the position advancing. Heartbeats have costs. They add write traffic, and the heartbeat job is another component that can fail silently, so alert on it as well.

This hygiene shortens incidents. When ownership and intent are clear, responders can stay in steps 1–3 instead of jumping to step 4 under disk pressure.

How can slot monitoring and retention limits save engineering time?

The time savings come from changing when and how engineers deal with a stalled slot, not from making any single query faster.

  • Fewer emergency outages. Without monitoring, the first sign of a stalled slot is often a primary that has stopped accepting writes. Responders then have to free disk space under pressure, bring the cluster back, and work out which slot caused the problem, all at once. Trend-based alerts turn that into a scheduled task: restart a connector or end an idle session while the primary is still healthy.
  • Faster diagnosis. The slot query and the pg_stat_activity query point straight at the slot and the cause: an inactive consumer, a stuck consumer, or a long transaction pinning restart_lsn. Responders do not have to search through pg_wal contents or guess from disk graphs.
  • Shorter handoffs. Slot names that identify an owner let on-call route the problem to the right team immediately, instead of asking around a shared channel to find out who created the slot.
  • Avoided resyncs. Each problem caught at steps 2 or 3 of the runbook avoids a snapshot, a full resync, and reconciliation work downstream, which is usually the most expensive part of a slot incident.
  • Bounded worst case. A sized max_slot_wal_keep_size replaces "the whole cluster is down" with "one consumer needs a resync." That is a smaller and more predictable unit of work, and it involves only the team that owns that consumer.
  • Less recurring toil. Decommissioning checklists and scheduled slot reviews remove abandoned slots before they become incidents. They also prevent the same investigation from happening repeatedly for slots nobody uses.

An illustrative estimate, with all inputs assumed: suppose a disk-full incident on a shared primary takes four engineers six hours across recovery, diagnosis, consumer resync, and data reconciliation. That is 24 engineer-hours. Suppose the same stalled consumer, caught by a time-to-full alert, takes one engineer one hour to restart it and confirm that the slot is advancing again. Under those assumptions, each early catch saves about 23 engineer-hours. Put your own incident history in place of these assumed figures before using them to justify the 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 shared variable is one edit and one review instead of editing every service's .env by hand.

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.
  • A wrong or stale value is caught at review time by the services it affects, not by a failed deploy.
  • 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.