Replication lag capacity
PostgreSQL WAL Retention & Replication Slot Planner
Convert a measured WAL byte rate and consumer outage into retained storage, disk headroom, and time remaining before a configured boundary.
WAL retention decision
Boundary timing
Decision guide
Replication slots protect consumers by retaining bytes on the primary
What this tool helps you decide
This planner estimates how much PostgreSQL write-ahead log remains after a standby, logical replication consumer, archive process, or other protected reader lags for a selected duration. It reports newly generated WAL, projected retained WAL, usable WAL disk after reserve, disk and optional slot-cap headroom, time to each boundary, and the shorter safe lag window. It helps set an operational recovery deadline before retained WAL fills the intended allocation.
Before you start
Measure WAL bytes generated over representative busy intervals using PostgreSQL statistics, LSN differences, or your monitoring system. Do not infer WAL from database size or transaction count alone. Record how many bytes are already retained for the affected consumer. Identify the actual filesystem allocation available to pg_wal after other use. If max_slot_wal_keep_size or another documented cap is relevant, enter its effective byte value; otherwise enter zero and treat disk reserve as the active boundary.
How the calculation works
New WAL equals measured GB per hour multiplied by lag hours. Projected retained WAL adds the bytes already retained. Usable WAL disk multiplies the entered allocation by one minus the reserve fraction. Time to the reserved disk boundary divides remaining usable capacity by WAL rate. An entered slot cap creates a second time and headroom calculation. Safe lag is the shorter of the disk and cap windows. The plan passes only when projected retention fits both active boundaries.
How to interpret the results
A pass means the constant-rate scenario fits, not that replication is healthy. The consumer could still be too far behind for the recovery objective, a cap could invalidate or stop protecting a slot depending on configuration and version, or a burst could cross the boundary earlier. A failure identifies an explicit response deadline: restore the consumer, reduce lag, add WAL capacity, or change retention safeguards after understanding data-loss consequences. Never drop a replication slot solely to clear disk without confirming its owner and recovery path.
Worked example
A primary generating 18 GB of WAL per hour already retains 40 GB. A 12-hour consumer outage adds 216 GB, for 256 GB projected. A 500 GB WAL allocation with 20% reserved permits 400 GB and leaves 144 GB of disk headroom. A 300 GB slot cap leaves 44 GB. The disk boundary is 20 hours from the starting point, while the cap is about 14.44 hours away, so the configured cap creates the shorter safe lag window.
Assumptions and limitations
WAL generation is treated as a constant measured byte rate. Real traffic can burst because of bulk changes, index work, full-page images, checkpoints, vacuum activity, and application releases. Multiple consumers can retain overlapping rather than simply additive segment ranges. The tool does not inspect slots, archive status, LSNs, segment rounding, timelines, failover, managed-service controls, disk alerts, or whether a consumer can catch up before further WAL is produced. Use it as a transparent scenario model, not a substitute for monitoring.
Next steps
Review the current official replication-slot warning and WAL retention documentation. Alert well before the modeled safe lag, test how your monitoring identifies inactive consumers, and document who may advance, recreate, or remove a slot. Recalculate after a workload or checkpoint-policy change. If the lag is caused by an index or table maintenance window, also run the Index Build & Reindex Space Planner. For physical-copy capacity, continue to the Base Backup Planner.