Parameter · Write-Ahead Log / Archiving
archive_command
Sets the shell command that will be called to archive a WAL file. An empty string means use "archive_library".
- Default:
'' (empty) - Type: string
- Applies: Reload
In plain words
When archiving is on, PostgreSQL runs this shell command once for every finished WAL file. %p is replaced by the file's path and %f by its name. The command must return success (exit code 0) only when the file is safely stored. If it fails, PostgreSQL keeps the file and retries, forever.
For DBAs and operators
Example (illustrative only, not robust): test ! -f /mnt/archive/%f && cp %p /mnt/archive/%f. Real setups use a backup tool (pgBackRest, WAL-G, Barman) that fsyncs, compresses and pushes asynchronously.
Rules
- Exit 0 only after the file is durable (fsynced) in the archive. Returning 0 too early silently breaks PITR.
- Must refuse to overwrite an existing different file, but should succeed if an identical file is already there (re-tries after a crash).
- Runs serially, one file at a time in the archiver: a slow command (e.g. 1 s per 16 MB) caps WAL throughput, and pg_wal grows.
- Used only when
archive_libraryis empty; setting both is an error: FATAL: both "archive_command" and "archive_library" set - Empty with archive_mode on: WAL is kept, waiting for a command.
Failures
LOG: archive command failed with exit code 1DETAIL: The failed archive command was: cp pg_wal/00000001000000000000000B /mnt/archive/00000001000000000000000BWARNING: archiving write-ahead log file "00000001000000000000000B" failed too many times, will try again later
Watch pg_stat_archiver.failed_count and the number of .ready files in pg_wal/archive_status. Can be changed with a reload.
How to change it
Change in postgresql.conf or ALTER SYSTEM, then run SELECT pg_reload_conf().
See it in context
Related parameters
archive_mode archive_library archive_timeout restore_command max_wal_size