PostgreSQL Replication Slots: Prevent WAL Retention From Filling Storage

A PostgreSQL replication slot can retain WAL while its consumer falls behind. Plan storage around the write rate, the outage you must tolerate and the recovery time you can afford. Extra IOPS do not solve a retention policy that lets an absent consumer hold WAL indefinitely.

The useful question is not simply how large the database is. It is how quickly the retained log can grow while a standby or change-data-capture consumer stops making progress. This guide uses PostgreSQL 18 documentation and proposes a capacity test. It reports no new Nirvana benchmark.

TL;DR

• Monitor retained WAL and disk headroom alongside consumer health.
• Assign an owner and a recovery policy to every replication slot.
• Understand the availability tradeoff before limiting retained WAL.
• Test a stopped consumer and its recovery on an isolated deployment.

Why can replication slots fill storage?

A slot keeps track of data that a replication consumer may still need. PostgreSQL's replication-slot documentation warns that slots can retain enough WAL to fill the space allocated to pg_wal. A disconnected consumer is therefore both a replication problem and a potential primary-capacity problem.

Do not interpret “inactive” as “safe to remove.” The consumer may be temporarily offline, recovering from maintenance, or part of a critical downstream pipeline. Establish what owns the slot and what rebuilding that consumer requires before considering a change.

Slot retention is also not the only reason WAL remains on disk. Check the archive path and other retention requirements before attributing every byte to one consumer. A slot's lag is a diagnostic signal, not a complete filesystem inventory.

Which signals should you inspect?

The pg_replication_slots reference defines the slot state fields. On a PostgreSQL 18 primary, an appropriately privileged operator can start with this read-only query:

SELECT slot_name, slot_type, active,
       restart_lsn, wal_status, safe_wal_size,
       pg_wal_lsn_diff(pg_current_wal_lsn(), restart_lsn)
         AS bytes_since_restart_lsn
FROM pg_replication_slots;

Match the query to the server version. Null values need interpretation, not conversion to zero. The distance from the current log position to restart_lsn estimates a WAL range; it is not the exact on-disk size of pg_wal. Several slots can retain overlapping ranges, so adding their distances can double-count the same WAL.

Collect the filesystem's actual free space, the observed WAL generation rate, archive failures and the downstream consumer's progress at the same timestamps. Keep a short history. A single low lag sample cannot show whether a consumer repeatedly disconnects overnight.

How much headroom should you reserve?

Build an explicit scenario instead of choosing a universal percentage. Consider the consumer outage, the time before somebody responds and the time needed to restore progress. Use observed busy-period WAL generation and leave room for other storage growth.

For example, suppose a planning exercise uses 12 GiB of WAL per hour and six hours without useful consumer progress. That scenario can generate 72 GiB before allowing for existing retained data, other database growth and operating reserve. Those figures are arithmetic examples, not measured Nirvana or PostgreSQL performance.

Now test the recovery assumption. If the consumer restarts but cannot catch up faster than new work arrives, retention may keep growing. Record the time until the backlog begins shrinking, not just the moment the process reconnects.

Use the scenario to set earlier warning and urgent response thresholds. Tie the alert to an owner and an action. “Disk 80% full” without an estimate of the remaining time may be too late for a write-heavy system and unnecessarily noisy for a quiet one.

Should you cap retained WAL?

PostgreSQL's replication settings document max_slot_wal_keep_size. Its default of -1 permits unlimited slot retention. A configured limit applies at checkpoint time; required WAL may then become unavailable to a consumer that falls too far behind. Treat this as a tradeoff between disk exposure and the ability to resume from the slot.

A limit is not a promise that the filesystem can never fill. Other retention needs and database files still consume capacity. Document what happens when the consumer exceeds the limit: who rebuilds it, from which source, how long that takes and how downstream correctness is checked.

For change-data-capture consumers, also define the business effect of a rebuild. A dashboard that can be regenerated and a pipeline feeding an external billing system have different recovery requirements. Do not select an automatic slot cleanup policy without the consumer owner's agreement.

What should a retention acceptance test include?

Use a disposable primary and consumer with a representative workload. Never create storage pressure deliberately on the production primary to validate this guide.

1. Establish the baseline: record workload rate, WAL growth, free space and consumer progress while everything is healthy.
2. Stop the test consumer: keep the writer running within a predefined safe capacity budget. Observe retained log growth and confirm alerts reach the operator.
3. Resume the consumer: measure reconnect time, catch-up time and when storage is reclaimed under the normal lifecycle.
4. Exercise the recovery policy: if a retention limit is part of the design, test the documented rebuild path separately. Verify acknowledged downstream records and duplicate handling.
5. Record the decision: retain the configuration, maximum observed exposure, alert response and recovery evidence together.

The pass condition is a bounded, understood recovery path. It is not merely that the primary stayed up during a short test. Repeat after material changes to write rate, retention settings or downstream processing.

Where does Nirvana storage fit?

Nirvana high performance block storage is a deployment option for stateful databases. Evaluate capacity, sustained application latency and recovery together. Storage performance and the policy controlling retained WAL solve different parts of the problem.

Use the PostgreSQL WAL and commit benchmarking guide for the write path, and the backup and checkpoint latency guide for maintenance contention. Neither replaces consumer monitoring or a tested retention budget.

FAQ

Does an inactive slot always mean the consumer is broken?

No. Determine the expected lifecycle and owner. Inactivity alone does not establish whether a slot is obsolete.

Can I add up slot lag to calculate disk usage?

No. Slots can retain overlapping WAL ranges. Compare log-position evidence with actual filesystem measurements.

Will faster storage stop WAL accumulation?

Only if a measured storage bottleneck is preventing progress and the change resolves it. A disconnected or logically stalled consumer needs a different fix.

Documentation reviewed 5 November 2026. Capacity figures are illustrative; no benchmark was run for this article.

About Nirvana Labs

Nirvana Labs is a high performance storage cloud built for blockchain, AI and databases: demanding, real-time, stateful workloads. Its high performance block storage, compute, private networking, Nirvana Kubernetes Service and Agent Sandboxes help teams build and operate data-intensive applications.

Learn more at Nirvana Labs.

Nirvana Cloud | Pricing | Blog | Docs | Changelog | LinkedIn | Twitter | Telegram | YouTube