archive_command

A configuration parameter determining how completed WAL segments are archived

archive_command is a configuration parameter which determines how completed WAL segments are sent to archive storage.

archive_command was added in PostgreSQL 8.0.

Default value

The default value for archive_command is: '' (empty string)

Usage

archive_mode must be set to on (PostgreSQL 9.5 and later: optionally always) for archive_command to be recognised.

Disabling WAL archiving

As archive_mode requires a PostgreSQL restart for changes to become effective, the recommended method of temporarily disabling WAL archiving is to set archive_command to an empty string (''), which will cause the command to fail. Archiving will resume onece a valid archive_command is set.

If archive_command is set to an arbitrary command which returns a zero exit status (success), e.g. /bin/true, WAL files ready for archiving will be removed without being archived. This also effectively disables archiving, but means there will be a break in the chain of archived WAL files, and unless the files are archived by another route, the archive will only be valid up until the last file archived before the archiving chain was broken.

Failure handling

If archive_command cannot be executed, PostgreSQL will retry execution up to 3 times, pausing 1 second between tries before emitting the following log message:

archiving write-ahead log file "..." failed too many times, will try again later

It will then wait up to 60 seconds before restarting a fresh attempt.

These values are hard-coded as NUM_ARCHIVE_RETRIES and PGARCH_AUTOWAKE_INTERVAL in src/backend/postmaster/pgarch.c.

Diagnosing issues

From PostgreSQL 9.4, the system catalogue view pg_stat_archiver can be used to determine if archive_command is failing.

Precise details of the failure can be found in the PostgreSQL log file and will look something like this:

[2019-06-10 21:51:43 UTC] node2 postgres [unknown] LOCATION:  ProcessStandbyReplyMessage, walsender.c:1788
cp: cannot create regular file "/home/backup/invalid-wal-dir/000000010000000000000001": No such file or directory
[2019-06-10 21:51:44 UTC]    LOG:  00000: archive command failed with exit code 1
[2019-06-10 21:51:44 UTC]    DETAIL:  The failed archive command was:
test ! -f /home/backup/invalid-wal-dir/000000010000000000000001 &&
cp pg_wal/000000010000000000000001 /home/backup/invalid-wal-dir/000000010000000000000001

Change history

Examples

Sample PostgreSQL log output when the archive_command command repeatedly fails:

cp: cannot create regular file '/var/log/archive/000000010000000000000001': No such file or directory
[2022-05-19 18:46:53 UTC]    LOG:  00000: archive command failed with exit code 1
[2022-05-19 18:46:53 UTC]    DETAIL:  The failed archive command was: test ! -f /var/log/archive/000000010000000000000001 && cp pg_wal/000000010000000000000001 /var/log/archive/000000010000000000000001
cp: cannot create regular file '/var/log/archive/000000010000000000000001': No such file or directory
[2022-05-19 18:46:54 UTC]    LOG:  00000: archive command failed with exit code 1
[2022-05-19 18:46:54 UTC]    DETAIL:  The failed archive command was: test ! -f /var/log/archive/000000010000000000000001 && cp pg_wal/000000010000000000000001 /var/log/archive/000000010000000000000001
cp: cannot create regular file '/var/log/archive/000000010000000000000001': No such file or directory
[2022-05-19 18:46:55 UTC]    LOG:  00000: archive command failed with exit code 1
[2022-05-19 18:46:55 UTC]    DETAIL:  The failed archive command was: test ! -f /var/log/archive/000000010000000000000001 && cp pg_wal/000000010000000000000001 /var/log/archive/000000010000000000000001
[2022-05-19 18:46:55 UTC]    LOCATION:  shell_archive_file, shell_archive.c:124
[2022-05-19 18:46:55 UTC]    WARNING:  01000: archiving write-ahead log file "000000010000000000000001" failed too many times, will try again later
...
cp: cannot create regular file '/var/log/archive/000000010000000000000001': No such file or directory
[2022-05-19 18:47:53 UTC]    LOG:  00000: archive command failed with exit code 1
...

Note that successful resumption of archiving is not logged.

Categories

GUC configuration item, Replication, Storage

See also

archive_mode, archive_timeout, pg_stat_archiver, restore_command