pg_archivecleanup

Clean an archive directory up to a given WAL file

$ pg_archivecleanup [path/to/archive] [path/to/walfile]

$ pg_archivecleanup [[-n|--dry-run]] [path/to/archive] [path/to/walfile]

$ pg_archivecleanup [[-x|--strip-extension]] [extension] [path/to/archive] [path/to/walfile]

$ pg_archivecleanup [[-b|--clean-backup-history]] [path/to/archive] [path/to/walfile]

$ pg_archivecleanup [[-d|--debug]] [path/to/archive] [path/to/walfile]

pg_archivecleanup [OPTION]... archivelocation oldestkeptwalfile

archivelocation
    The path to the directory containing the WAL archive files to be cleaned up.

oldestkeptwalfile
    The name of the oldest WAL file that must be preserved. All files older than this will be removed.

-d, --debug
    Enables debug output, providing more verbose information about the cleanup process.

-n, --dry-run
    Performs a 'dry run'. It shows which files would be removed without actually deleting them.

-V, --version
    Displays the PostgreSQL version information and exits.

-?, --help
    Shows a help message about command usage and options, then exits.

The pg_archivecleanup command is a utility provided with PostgreSQL to manage and clean up old Write-Ahead Log (WAL) segment files from a continuous archiving directory. It helps prevent the WAL archive from growing indefinitely, which is crucial for efficient disk space management, especially in setups utilizing Point-In-Time Recovery (PITR) or streaming replication.

This utility is typically run on a standby server or recovery instance as part of the archive_cleanup_command configuration. It removes all WAL files in the specified archivelocation that are older than the oldestkeptwalfile argument. The oldestkeptwalfile is usually supplied by PostgreSQL itself (via the %r placeholder in the cleanup command) and represents the earliest WAL segment still required for the standby to recover up to the current point or for future PITR operations.

By automating the removal of no-longer-needed WAL segments, pg_archivecleanup ensures that the archive directory maintains a reasonable size while still preserving all necessary files for successful recovery.

Using pg_archivecleanup incorrectly can lead to the deletion of essential WAL files, which would prevent successful Point-In-Time Recovery (PITR) or break standby replication. Always ensure the oldestkeptwalfile is correct.

The command requires write permissions to the specified archivelocation.

It only deletes full WAL segments and does not touch partial WAL files (those ending in .partial) or backup history files (those ending in .backup) which might also reside in the archive directory.

pg_archivecleanup is most commonly used by configuring the archive_cleanup_command parameter in the recovery.conf (or standby.signal/postgresql.conf for modern versions) file on a standby or recovery server. PostgreSQL will automatically execute this command whenever it determines that a certain WAL segment is no longer needed for recovery.

A typical configuration looks like this:
archive_cleanup_command = 'pg_archivecleanup /path/to/wal_archive %r'

Here, %r is a special placeholder provided by PostgreSQL that expands to the name of the oldest WAL file that the standby server still requires for recovery. This ensures that only truly obsolete files are removed, safeguarding data integrity and recovery capabilities.

pg_archivecleanup has been a standard utility distributed with PostgreSQL for many years, evolving alongside the database's robust continuous archiving and Point-In-Time Recovery (PITR) capabilities. Its development reflects the growing need for automated and reliable WAL archive management in high-availability and disaster recovery setups.

pg_basebackup(1), pg_rewind(1), pg_ctl(1), archive_cleanup_command (PostgreSQL Configuration)