Handling Write-Ahead Log Bloat

You will manage WAL retention policies to keep physical storage growth under control.

In this lesson, you will learn how to prevent your disk storage from being overwhelmed by unconsumed Write-Ahead Log (WAL) files.

The Problem: Why WAL Files Accumulate

PostgreSQL uses a Write-Ahead Log (WAL) to ensure durability; every change is written to these files before being applied to the data pages. Under normal operation, PostgreSQL recycles these files once they have been archived or consumed by standby replicas. However, if a standby server goes offline, or if an archive process (like archive_command) fails, the primary server cannot delete or reuse the old WAL files. This leads to "WAL bloat," where the pg_wal directory grows until it consumes all available disk space, eventually forcing the database to shut down.

Managing Retention Policies

To keep physical storage growth under control, you must align your WAL retention settings with your operational needs.

max_wal_size: This setting defines the "soft limit" for WAL growth during normal operation. When reached, PostgreSQL will trigger a checkpoint more aggressively to recycle space.
min_wal_size: This keeps a reserve of WAL files ready for use, which prevents constant allocation and deallocation overhead.
max_slot_wal_keep_size: This is your best defense against replication-related bloat. By setting a hard limit on how much WAL a physical replication slot can retain, you prevent a disconnected standby from causing the primary to run out of disk space.

If you are using archiving, ensure your archive_command is robust. If the command fails, the WAL files accumulate indefinitely. You can monitor the size of your WAL directory using:

SELECT pg_size_pretty(pg_ls_waldir());

If you notice the directory size climbing, check the status of your replication slots:

SELECT slot_name, restart_lsn, active 
FROM pg_replication_slots;

If a slot is inactive and the restart_lsn is very old, it is holding onto segments that the system cannot clear. You may need to drop the inactive slot to reclaim that space immediately.

Key Takeaway: WAL bloat is almost always caused by stale replication slots or failing archive processes; managing these via hard limits like max_slot_wal_keep_size is essential to prevent disk exhaustion.