Architecture and operating model
A PostgreSQL replication slot prevents removal of WAL that a physical standby or logical consumer has not received. When the consumer stops, the slot stops advancing and `pg_wal` can grow. A slot is not a data copy; it preserves a required WAL position and logical decoding state. An unmonitored slot can consume disk and affect primary availability.
For physical slots, `restart_lsn` marks retained WAL; logical slots also expose `confirmed_flush_lsn`. `pg_wal_lsn_diff(pg_current_wal_lsn(), restart_lsn)` estimates retained bytes. `wal_status` can be reserved, extended, unreserved or lost. `safe_wal_size` estimates additional WAL before danger of loss under a configured cap; `max_slot_wal_keep_size=-1` means unlimited retention.
Causes include consumer outage, networking, permissions, long transactions, decoding plugins and downstream backpressure. Dropping a slot can relieve disk pressure but prevents resume from that position and may require a fresh seed. Identify the owner, consumer RPO, current LSN and resynchronization plan first. Under pressure, calculate WAL growth and time to the disk threshold.
Alert per slot on lag, retained bytes, inactive time, wal_status and disk fullness. Size a limit from maximum accepted consumer outage × peak WAL generation. `max_slot_wal_keep_size` can cap exposure but may let the slot become lost after exceeding the limit. It is a controlled resynchronization boundary, not an automatic repair.
- 1Primary WAL generation
- 2Slot restart or confirmed LSN
- 3Standby or logical consumer
- 4Progress, retention cap and disk alarm
Design parameters
- WAL generation
- Measure P95 and peak hourly WAL over a complete business cycle.
- Outage tolerance
- Record maximum consumer downtime and the rebuild method for each slot.
- Slot cap
- Choose max_slot_wal_keep_size from disk, RPO and seed duration together.
- Disk budget
- Reserve separate thresholds for pg_wal, archive, temporary files and the OS.
- Ownership
- Map every slot to an application, team, contact and expiry date.
Worked example
At 120 GiB/hour peak WAL and a four-hour logical-consumer outage target, one slot requires 480 GiB retention. A 25% variation margin raises that to 600 GiB before other slots and archive space. With only 350 GiB free, the four-hour RPO cannot be met physically.
If retained WAL is 240 GiB and grows at 80 GiB/hour with 400 GiB free, the theoretical runway is five hours. Operational fullness thresholds shorten it. If repair takes 30 minutes and a new seed takes three hours, the decision owner should compare those times and replay impact.
Example commands: replace lab values and confirm permissions and software versions before use.
SELECT slot_name,slot_type,active,active_pid,restart_lsn,confirmed_flush_lsn,wal_status,safe_wal_size,
pg_size_pretty(pg_wal_lsn_diff(pg_current_wal_lsn(),restart_lsn)) AS retained
FROM pg_replication_slots ORDER BY pg_wal_lsn_diff(pg_current_wal_lsn(),restart_lsn) DESC;
SELECT pg_size_pretty(sum(size)) FROM pg_ls_waldir();
SHOW max_slot_wal_keep_size;
SELECT pid,usename,application_name,state,write_lag,flush_lag,replay_lag FROM pg_stat_replication;Troubleshooting
| Observation | Likely cause / distinction | Verification |
|---|---|---|
| pg_wal grows quickly | An inactive or lagging slot may retain old WAL. | Compare byte lag, active state and WAL generation for every slot. |
| wal_status is lost | Required WAL may have been removed after the cap; resume is not possible. | Verify the consumer error and start LSN, then follow the reseed plan. |
| Active slot does not advance | Downstream pressure, a long transaction or delayed flush acknowledgement may exist. | Track confirmed_flush_lsn, consumer queue and long transactions. |
| Slot cannot be dropped | An active connection may use it or the wrong slot may be targeted. | Verify active_pid, slot_type, database and application owner. |
Acceptance checks
- Map all slots to owners and consumers.
- Measure restart-LSN lag in bytes and trend it.
- Calculate safe disk time from peak WAL per hour.
- Alert on wal_status and safe_wal_size.
- Approve a reseed plan before drop or cap changes.
- Validate consumer LSN progress and disk recovery afterward.
Related concepts
Transaction logs and recovery chains
WAL, redo and transaction-log mechanisms record changes in order for durability and recovery, with product-specific details. Data copies and logs must belong to compatible timelines and chains. Having log files alone does not prove point-in-time recovery: a valid base backup and the required uninterrupted log range are also needed. Measure archival lag, log volume and replay time. Do not delete logs arbitrarily to regain space; use supported retention and cleanup methods.
Replication scope
Replication transfers data or state changes to another copy. Synchronous transfer can introduce latency and connectivity dependence; asynchronous transfer can lag behind. A current replica is not necessarily protected from incorrect changes: deletion and corruption can propagate too. Compare lag with the application’s last committed operation, not merely connection status. Define which copy receives write authority after the source is lost and how the old node is reconciled when it returns. Report replication lag and the actual recoverable point separately.
Capacity and usable headroom
Raw capacity is not the capacity available to applications. RAID or erasure coding, filesystems, reserved space, metadata, snapshots and growth headroom are separate deductions. TB and TiB representations also change the displayed number. Write calculations with units, establish protected usable capacity, then subtract operating reserves. Track growth rate as well as current utilization. The projected exhaustion date should leave enough time to procure and deploy additional capacity.
Retention and capacity
Retention defines which recovery points are kept and for how long. Daily, weekly and monthly points do not represent identical change patterns; full-copy creation and chain dependencies affect physical capacity. Retention decisions combine business requirements, applicable obligations and technical capacity. Longer retention does not automatically provide better recovery: the right point must be discoverable and readable. When changing a policy, test whether existing points are deleted immediately or handled differently by the product.
Availability versus recovery
High availability aims to keep service running through specified failures with a short interruption; backup recovers lost or corrupted data from an earlier point. A cluster can replicate an accidental deletion to another node. HA therefore does not replace backup. Consider DNS, identity, network, storage and power dependencies together. Successful node failover is insufficient by itself: measure user sessions, application writes and external integrations after the transition as well.
Telemetry and time correlation
Telemetry combines logs, metrics and events that explain system behavior. A log describes an event, a metric shows behavior over time, and a distributed trace follows a request across components. Clock differences can make one event appear to occur at several times. Use synchronized clocks, reliable source identifiers and consistent time-zone handling. Alarm design should consider duration and user impact alongside thresholds. Monitor gaps in collection separately: absence of logs must not be interpreted as absence of incidents.
Primary documentation
Prepared by the Doz Teknoloji technical team using the primary references below. Calculations and lab scenarios state their assumptions; validate the applicable product version before rollout.