archive_command

Definition PG 18 manual

The local shell command to execute to archive a completed WAL file segment. Any %p in the string is replaced by the path name of the file to archive, and any %f is replaced by only the file name. (The path name is relative to the working directory of the server, i.e., the cluster's data directory.) Use %% to embed an actual % character in the command. It is important for the command to return a zero exit status only if it succeeds. For more information see Section 25.3.1.

This parameter can only be set in the postgresql.conf file or on the server command line. It is only used if archive_mode was enabled at server start and archive_library is set to an empty string. If both archive_command and archive_library are set, an error will be raised. If archive_command is an empty string (the default) while archive_mode is enabled (and archive_library is set to an empty string), WAL archiving is temporarily disabled, but the server continues to accumulate WAL segment files in the expectation that a command will soon be provided. Setting archive_command to a command that does nothing but return true, e.g., /bin/true (REM on Windows), effectively disables archiving, but also breaks the chain of WAL files needed for archive recovery, so it should only be used in unusual circumstances.

How it works

Sets the shell command that will be called to archive a WAL file. A configuration reload applies a new value; existing work already in flight is not retroactively changed.

The archiver expands %p to the source path and %f to the WAL file name, and considers exit status zero a durable success. A nonzero result is retried; a false success allows PostgreSQL to recycle the only local copy and silently breaks the archive chain.

Monitor and change archive_command together with archive_mode, archive_library, archive_timeout. Validate on the relevant server role and real workload, then use its sighup context to choose session change, reload, or restart; a historical boot default is not the current effective value.

Operational considerations

Returning success before the archive copy is durable or verified.

Failing to quote %p/%f safely in a shell command.

Letting repeated failures fill pg_wal and stop the server.

Confusing pg_settings base units with human-readable configuration units.

Benchmarking throughput without a crash-recovery and archive-restore test.

Workload guidance

OLAP: Provision archive throughput and capacity for bulk-load WAL peaks. If archiving falls behind, throttle the job and alert; never hide backlog with false success or aggressive cleanup.

OLTP: Manage archive_command as part of the backup/restore protocol: the command or module must be idempotent, fail visibly, and be verified by restoring from the real archive—not merely by exit status.

SMALL: Enable it only for a defined PITR requirement and use a mature backup tool. Keep rebuildable instances simple, but never install a no-op command that creates the illusion of a backup.