Context
A PostgreSQL replication slot remembers which write-ahead log, or WAL, a consumer may still need. That protects a disconnected replica or decoder from losing its place. It can also retain a growing amount of WAL when the consumer stops making progress. The operational question is which consumer owns the retention and how it can recover.
Prerequisites
Identify the PostgreSQL major version, physical and logical consumers, slot names, consumer owners, archive coverage, and available storage. This guide uses current PostgreSQL 18 documentation; fields and retention controls can differ on older releases. Obtain authorized access to slot and replication statistics. Record a baseline before changing anything, especially when multiple subscribers share the same database cluster.
Investigate the retained history
- Read
pg_replication_slots, including slot name, type, active state, restart position, and available WAL-status fields. An inactive slot is not automatically obsolete: its consumer may be paused intentionally. Match each slot to a named service and owner. Treat an unknown owner as an inventory problem requiring investigation, not permission to delete the slot. - Estimate retained bytes with a read-only query such as
SELECT slot_name, active, pg_wal_lsn_diff(pg_current_wal_lsn(), restart_lsn) AS retained_bytes FROM pg_replication_slots;. Run it on the primary and interpret null positions explicitly. Compare repeated samples because a single large value says little about whether the consumer is catching up. - Check the consumer's connection, authentication, apply errors, and processing progress. For logical replication, successful delivery does not guarantee successful application. For physical replication, examine the standby and network path. Align consumer logs with WAL growth rather than assuming the oldest inactive slot explains every file in
pg_wal. - Choose a recovery action with the consumer owner. Restoring consumer connectivity may release retention naturally. Removing an abandoned slot or imposing a retention limit changes the consumer's recovery options and must be planned. A retention cap can prevent unlimited growth but may leave required WAL unavailable, forcing reinitialization or another supported recovery path.
Diagnostic table
| Finding | Likely meaning | Next evidence |
|---|---|---|
| Inactive slot, growing retained bytes | Consumer disconnected | Owner and last successful progress |
| Active slot, little progress | Connected but constrained | Consumer apply or decode errors |
| Several slots lag | Shared bottleneck possible | Network and workload timeline |
| WAL status indicates missing history | Catch-up may be impossible | Supported consumer recovery plan |
Illustrative scenario
A change-data-capture connector is retired, but its logical slot remains. WAL keeps accumulating even though normal replicas are healthy. The team confirms retirement with the application owner, preserves the connector's last checkpoint, and removes the abandoned slot through its approved procedure. It then verifies storage behavior. The decisive evidence is ownership and lifecycle state, not merely inactivity.
Correction and verification
After reconnecting or retiring a consumer, confirm that its restart position advances or that the intentionally removed slot is absent. Observe retained-byte trends and disk space across normal checkpoints. WAL recycling may not produce an immediate filesystem size decrease. Check archive health separately, since archive failures can retain WAL independently of slots.
Operating procedure
Maintain a slot registry with owner, purpose, expected outage window, and rebuild procedure. Alert on retained bytes and lack of progress with enough storage headroom for intervention. Review slots when connectors, subscriptions, or standbys are decommissioned. Record the consumer recovery consequence of every retention-policy change so capacity protection never silently becomes a broken recovery assumption.
Explore Clouvenix database administration for implementation and operational handover.