archive_cleanup_command

Definition PG 18 manual

This optional parameter specifies a shell command that will be executed at every restartpoint. The purpose of archive_cleanup_command is to provide a mechanism for cleaning up old archived WAL files that are no longer needed by the standby server. Any %r is replaced by the name of the file containing the last valid restart point. That is the earliest file that must be kept to allow a restore to be restartable, and so all files earlier than %r may be safely removed. This information can be used to truncate the archive to just the minimum required to support restart from the current restore. The pg_archivecleanup module is often used in archive_cleanup_command for single-standby configurations, for example:

archive_cleanup_command = 'pg_archivecleanup /mnt/server/archivedir %r'

Note however that if multiple standby servers are restoring from the same archive directory, you will need to ensure that you do not delete WAL files until they are no longer needed by any of the servers. archive_cleanup_command would typically be used in a warm-standby configuration (see Section 26.2). Write %% to embed an actual % character in the command.

If the command returns a nonzero exit status then a warning log message will be written. An exception is that if the command was terminated by a signal or an error by the shell (such as command not found), a fatal error will be raised.

This parameter can only be set in the postgresql.conf file or on the server command line.

How it works

Sets the shell command that will be executed at every restart point. A configuration reload applies a new value; existing work already in flight is not retroactively changed.

At every restartpoint during archive recovery, PostgreSQL expands %r to the oldest WAL file still needed for a restartable recovery and runs this command. pg_archivecleanup is the usual implementation, but deleting from an archive shared by several standbys can strand another consumer.

Monitor and change archive_cleanup_command together with archive_mode, archive_command, archive_library. Validate on the relevant server role and real workload, then use its sighup context to choose session change, reload, or restart; a historical boot default is not the current effective value.

Operational considerations

Running destructive cleanup against an archive shared by other standbys or restore jobs.

Misreading %r as the last replayed file; it is the earliest file needed to keep recovery restartable.

Using a command that is not idempotent when a restartpoint repeats or an archive file is already absent.

Assuming a reload executes the command immediately; it runs at recovery restartpoints.

Letting shell quoting or an unexpected archive path turn cleanup into deletion outside the intended archive.

Workload guidance

OLAP: Provision archive throughput and capacity for bulk-load WAL peaks. If archiving falls behind, throttle the job and alert; never hide backlog with false success or aggressive cleanup.

OLTP: Manage archive_cleanup_command as part of the backup/restore protocol: the command or module must be idempotent, fail visibly, and be verified by restoring from the real archive—not merely by exit status.

SMALL: Enable it only for a defined PITR requirement and use a mature backup tool. Keep rebuildable instances simple, but never install a no-op command that creates the illusion of a backup.