archive_timeout

Definition PG 18 manual

The archive_command or archive_library is only invoked for completed WAL segments. Hence, if your server generates little WAL traffic (or has slack periods where it does so), there could be a long delay between the completion of a transaction and its safe recording in archive storage. To limit how old unarchived data can be, you can set archive_timeout to force the server to switch to a new WAL segment file periodically. When this parameter is greater than zero, the server will switch to a new segment file whenever this amount of time has elapsed since the last segment file switch, and there has been any database activity, including a single checkpoint (checkpoints are skipped if there is no database activity). Note that archived files that are closed early due to a forced switch are still the same length as completely full files. Therefore, it is unwise to use a very short archive_timeout — it will bloat your archive storage. archive_timeout settings of a minute or so are usually reasonable. You should consider using streaming replication, instead of archiving, if you want data to be copied off the primary server more quickly than that. If this value is specified without units, it is taken as seconds. This parameter can only be set in the postgresql.conf file or on the server command line.

How it works

Sets the amount of time to wait before forcing a switch to the next WAL file. A configuration reload applies a new value; existing work already in flight is not retroactively changed.

When no natural segment switch occurs within the interval, PostgreSQL forces one so the current partial segment can be archived. It does not make WAL records durable sooner, and very small values waste archive space because archived segment files retain full segment size.

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

Treating it as a commit-durability timeout.

Choosing a tiny interval and multiplying archive storage by mostly empty full-size segments.

Assuming forced switches solve a slow or failed archiver.

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