archive_cleanup_command — PostgreSQL configuration parameter

This optional parameter specifies a shell command that will be executed at every restartpoint.

At a glance

What it does

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 restartpoint. 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 pgarchivecleanup 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 warm_standby). 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.

(Description quoted from the official PostgreSQL documentation.)

How to apply a change

Can be set per session with SET, per role/database with ALTER ROLE/DATABASE ... SET, or globally in postgresql.conf.

Inspect the current value and source with SHOW archive_cleanup_command; or SELECT name, setting, unit, context, source FROM pg_settings WHERE name = 'archive_cleanup_command';.

Tuning guidance

This is a point-in-time-recovery control, used only while restoring a backup, not during normal operation. Set it in the recovery configuration to define the exact stopping point or restore action you want, perform the recovery, then remove it. It has no effect on a normally running primary.

Reference

PostgreSQL documentation — archive_cleanup_command.