Archiver

For DBAs and operators

The work loop

1. Wake on its latch (set when a segment is marked .ready), or after 60 seconds at the latest.
2. Scan pg_wal/archive_status/ for .ready files, oldest first (it remembers up to 64 candidates per directory scan instead of rescanning for each file; timeline history files go first).
3. For each: run archive_command with %p (path relative to the data directory) and %f (file name), or call the archive_library module's callback (PostgreSQL 15+; basic_archive is shipped as an example).
4. Success: rename to .done, update pg_stat_archiver. Failure: retry after 1 second; after 3 failures in a row give up for now and sleep (60 s or until woken by the next segment).

Real log lines from a failing command:

How to see it

One process, started by the postmaster when archive_mode is on (or always, which also archives on a standby). ps shows its last result in the title: postgres: archiver last was 000000010000000000000011 or postgres: archiver failed on 000000010000000000000012. backend_type = 'archiver', wait_event ArchiverMain while idle, ArchiveCommand while the command runs.

SELECT archived_count, last_archived_wal, last_archived_time,
       failed_count, last_failed_wal, last_failed_time
  FROM pg_stat_archiver;

-- how many segments are waiting?
SELECT count(*) FROM pg_ls_archive_statusdir()
 WHERE name LIKE '%.ready';

If last_failed_time is newer than last_archived_time, archiving is currently stuck.

Rules for archive_command

• Return 0 only when the file is safely stored (fsynced). Returning 0 too early loses WAL silently.
• Refuse to overwrite an existing different file (test ! -f), but returning success for an identical copy is fine and helps after a crash between copy and rename.
• It runs serially, one segment at a time: a slow command (high latency to S3, compression) becomes a backlog under heavy write load. Tools such as pgBackRest offer asynchronous archiving with parallel pushes.
• Changing archive_command needs only a reload; archive_mode needs a restart. Setting both archive_command and archive_library is an error since PostgreSQL 16.
• archive_timeout can force a segment switch on quiet systems so completed WAL becomes archivable sooner. Each switch still produces a complete WAL segment file: 16 MB by default, or whatever wal_segment_size was chosen when the cluster was initialized.

Typical support case: pg_wal is full

Check pg_stat_archiver and the server log first. Fix the cause (permissions, full archive volume, expired credentials, missing directory) and the backlog drains by itself. Never delete files from pg_wal by hand. When the disk does fill up, the server stops with a PANIC such as PANIC: could not write to file "pg_wal/xlogtemp.1234": No space left on device Free space elsewhere or extend the volume, then start it again. Other WAL retainers to check: replication slots (pg_replication_slots.wal_status) and wal_keep_size.

If it dies

If the archive command is killed by a signal, the archiver exits with a FATAL error, for example FATAL: archive command was terminated by signal 9: Killed (or FATAL: archive command failed with exit code 137 when the shell reports the signal), and the postmaster starts a new one; nothing is lost because the .ready files are still there. If the archiver process itself is killed with SIGKILL, the postmaster performs a crash restart of the whole server.