When a replica stops, how long should the primary keep the logs it needs to catch up? A mechanism designed to help recovery can consume storage on the server that is still accepting writes.

Christophe Pettus’s discussion of max_slot_wal_keep_size provides a useful starting point. A finite limit can constrain WAL retention, but reaching it may leave a consumer needing recovery.

For deployments using replication slots, the limit and the recovery path belong in the same decision. Connecting retention behavior, capacity estimates, and monitoring makes the required headroom easier to judge.

Replication slots retain WAL after a consumer stops

WAL records database changes. Replication slots prevent a sender from discarding WAL that a consumer still needs. Required resources remain protected even when the connection disappears, as documented in the logical decoding concepts.

The retention starting point is the slot’s restart_lsn. If consumer processing stops and that position does not advance while writes continue, the required WAL range grows. The same mechanism that supports reconnection therefore consumes storage.

The retention limit arrived in PostgreSQL 13, released on September 24, 2020. This is an operational decision about an existing setting; the explanations and SQL here use PostgreSQL 18 as their reference.

With the default -1, slots can retain unlimited WAL. A finite max_slot_wal_keep_size constrains retention at checkpoints; a slot that loses required WAL cannot continue replication. These conditions are defined in the configuration documentation.

A WAL retention limit is not a disk usage ceiling

Setting a cap does not guarantee that pg_wal stays below that size. Enforcement happens at checkpoints, so storage must also accommodate WAL generated between them.

The similarly named settings serve different purposes.

Slots can use WAL retained by wal_keep_size. A large floor can therefore prevent a smaller slot limit from reducing retention as expected. Archiving failures can also accumulate old, unarchived WAL. The WAL configuration documentation describes these retention conditions.

Monitor slot headroom and disk free space separately. Limiting slot retention does not resolve storage pressure caused by failed archiving.

Convert an acceptable outage into a WAL budget

Start with how long you want to wait for a consumer, rather than a supposedly typical number of gigabytes. For capacity planning, peak WAL generation rate multiplied by the acceptable outage gives an estimate of additional retention while a consumer is completely stopped.

Suppose WAL generation stays at 8 MiB per second for 30 minutes. That is 8 × 30 × 60 = 14,400 MiB, or approximately 14.1 GiB. This is an illustrative assumption, not a measurement or a recommended setting.

Account for existing lag and headroom while the consumer catches up after restarting. The WAL volume also needs room for normal operation and growth between checkpoints. If the desired waiting period does not fit, reconsider the outage allowance, storage capacity, or recovery approach.

To measure generation, sample pg_current_wal_lsn() on the primary at an interval and divide the position difference by elapsed seconds. pg_wal_lsn_diff() returns that difference in bytes. LSNs describe WAL positions, not growth of the database itself. Use the administration function definitions and include busy periods such as batch processing in your measurements.

Read slot headroom together with its state

Once the budget is chosen, monitor how much remains. This read-only SQL inspects settings and slots on a PostgreSQL 18 primary.

-- Read effective WAL retention settings.
SHOW max_slot_wal_keep_size;
SHOW wal_keep_size;
SHOW max_wal_size;

-- Read each slot's state and retention starting point.
SELECT slot_name,
       slot_type,
       active,
       restart_lsn,
       wal_status,
       safe_wal_size
FROM pg_replication_slots
ORDER BY slot_name;

safe_wal_size measures additional WAL bytes before the slot risks becoming lost; it does not measure disk free space. It can be NULL with unlimited retention or an already lost slot. Read it alongside the states defined in pg_replication_slots.

extended alone does not establish a failure, and unreserved can return to a retained state. A practical monitoring design combines state changes, declining headroom, and disk free space, with alerts early enough for an operator to respond.

Decide how to restore consumers before choosing the cap

The recovery cost of losing WAL depends on the consumer. A physical standby can catch up from an archive when the required WAL remains available through restore_command. If the required WAL is unavailable everywhere, it needs a new base backup. Use the documented standby recovery paths to prepare a procedure that also addresses slot recreation.

For logical replication, creating a new slot does not restore missing change history. The exported snapshot mechanism explains how consistent data can be paired with a new slot. Plan how to restore consistency, including subscriber resynchronization or an initial copy where needed.

The answer to the opening question is to wait for the time needed to restore the consumer, within a storage budget the primary can afford. Measuring WAL generation and combining a finite budget with monitoring and a recovery procedure makes the behavior after reaching the cap part of the operational design.

Source

• Title: Christophe Pettus: All Your GUCs in a Row: max_slot_wal_keep_size
• URL: https://postgr.es/p/9vI