Context
PostgreSQL may retain WAL when its archive process cannot safely hand completed segments to the configured destination. The local filesystem then grows while the database continues serving requests. Treat this as a delivery-path failure: checkpoint tuning does not repair a destination that is full, inaccessible, or incorrectly reporting success.
Prerequisites and boundaries
Collect the PostgreSQL major version, archive configuration, destination location, service identity, backup design, and filesystem capacity. Obtain read access to logs and archiver statistics without exposing archive credentials. This guide follows current PostgreSQL documentation and focuses on archiving, rather than replication-slot retention. Check those other retention causes when the archive path appears healthy. Never remove files directly from pg_wal to regain space.
Follow archive delivery
- Inspect
pg_stat_archiver, including recent success and failure information, and record a timestamped sample. Correlate it with PostgreSQL logs. Some failures need the logs for their full explanation, so do not treat a counter as a complete error report. A server restart or statistics reset can also change the apparent history. - Review the configured archive command or archive library and the identity under which it operates. Determine whether it can resolve, reach, authenticate to, and write to the destination. Check available capacity and any quota on both ends. A successful manual test under an administrator account does not prove that the PostgreSQL service identity has equivalent access.
- Verify delivery of a recently completed segment at the intended destination. Use the archive mechanism's supported verification process and compare names, sizes, and integrity metadata where available. Review how duplicate destination filenames are handled. A command that returns success without preserving the correct file can hide a broken recovery path behind reassuring statistics.
- Repair the demonstrated boundary and let the supported archiver retry. For a capacity failure, restore destination capacity or select an approved destination change. For permissions or expired credentials, update the service-specific access and verify it narrowly. Avoid bypasses that return success while discarding WAL, since that would trade visible disk pressure for an invisible recovery gap.
Diagnostic table
| Observation | Investigation | Corrective direction |
|---|---|---|
| Failures coincide with destination quota | Archive capacity exhausted | Restore space and delivery |
| Manual copy works only as administrator | Service identity differs | Repair scoped permissions |
| Success reported, segment absent | Command success contract broken | Correct and audit delivery logic |
| Archive works, local WAL still grows | Another retention cause | Check slots and workload generation |
Illustrative scenario
A backup destination enforces a storage quota that the source server cannot see. The archive script begins failing, and local WAL grows overnight. Operations raises destination capacity after confirming retention ownership, then watches successive archive deliveries and local growth stabilize. The team also audits the affected interval for missing archive files. More local disk buys time but does not close the archive gap by itself.
Verify recovery of service
Confirm fresh archive successes over multiple segments and inspect the destination with the same supported verification process. Check the affected backup's required WAL coverage, then perform an isolated recovery exercise when appropriate. Reassess local capacity after normal cleanup opportunities; immediate shrinkage is not the only sign of progress. Preserve original errors and the repaired configuration for review.
Monitoring and SOP
Alert on archive failure, time since expected successful delivery, local free space, and destination capacity. Account for quiet workloads that may not complete a segment frequently. Assign ownership for the script, credentials, destination retention, and recovery testing. Include the archive contract in change review: a successful exit status should mean the intended recoverable object has actually been secured.
Explore Clouvenix backup disaster recovery for implementation and operational handover.