archive_command
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
- PostgreSQL 8.0
- added (commit 66ec2db7)
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.
References
- PostgreSQL documentation: archive_command