archive_library

Definition PG 18 manual

The library to use for archiving completed WAL file segments. If set to an empty string (the default), archiving via shell is enabled, and archive_command is used. If both archive_command and archive_library are set, an error will be raised. Otherwise, the specified shared library is used for archiving. The WAL archiver process is restarted by the postmaster when this parameter changes. For more information, see Section 25.3.1 and Chapter 49.

This parameter can only be set in the postgresql.conf file or on the server command line.

How it works

Sets the library 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.

A nonempty library selects an archive module through its _PG_archive_module_init callback instead of a shell command. archive_command and archive_library are alternative implementations; changing either is reloadable, while archive_mode must already be active.

Monitor and change archive_library together with archive_mode, archive_command, 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

Configuring both a library and expecting archive_command to run as a fallback.

Loading untrusted in-process archive code.

Treating module success as proof that restores work.

Reloading to a new module without verifying backlog processing, failure reporting, and rollback behavior.

Letting repeated module failures retain WAL until pg_wal fills, without an archive-lag alert.

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_library 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.