# archive_timeout

> archive_timeout — Sets the amount of time to wait before forcing a switch to the next WAL file. Observed in PG9.0–19 Beta 3; its last measured boot default is 0 s in PG19 Beta 3, with sighup context. This is a beta-snapshot fact and can change before PostgreSQL 19 GA.
---

> [!NOTE]
> **Fact — official short description:** “Sets the amount of time to wait before forcing a switch to the next WAL file.”

## Identity {#identity}

| Field | Value | Meaning |
| --- | --- | --- |
| Type | `integer` | Upstream pg_settings type |
| Context | `sighup` | Takes effect after configuration reload |
| Unit | `s` | Raw unit |
| Range | `0` – `1073741823` | Raw limits in the last observed version |
| Enum values | — | — for non-enum types |
| Category | Write-Ahead Log / Archiving | Upstream classification |
| Latest boot value | `0` | 0 s |
{.fields meta="-"}

## Lifecycle {#lifecycle}

| Fact | Value |
| --- | --- |
| First observed | PG9.0 (research boundary) |
| Present in | PG9.0–19 Beta 3 |
| Removed in | No |
| Introduction commit | Not asserted: predates the PG9.0 research boundary |
| Commit date | — |
| Discussion | — |

## Default history {#default-history}

| Versions | Raw `boot_val` | Unit | Human value |
| --- | --- | --- | --- |
| PG9.0–19 Beta 3 | `0` | `s` | 0 s |
{.full-width caption="Measured PG9.0–19 Beta 3 boot defaults"}

## How it works {#mechanism}

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.

## Tuning advice {#tuning-advice}

> [!TIP]
> **Advice.** These are workload-specific starting points and must be validated with measurements.

| Workload | Guidance |
| --- | --- |
| 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. |
| 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. |
| Small nodes | 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. |
{.full-width}

## Pigsty {#pigsty}

Values use the fixed 8-vCPU, 32-GiB, 100-GiB SSD fixture and render the current Pigsty templates for PG19 Beta 3; this does not assert current Pigsty support for that historical or beta release.

| Template | Effective value | Versus upstream boot | Source expression |
| --- | --- | --- | --- |
| OLTP | `300` | different | `300` |
| OLAP | `300` | different | `300` |
| CRIT | `300` | different | `300` |
| TINY | `300` | different | `300` |
{.full-width}

> [!CAUTION]
> **Advice — pending human review.** Fact from the current Pigsty template projection: OLTP: PG9.0–19 Beta 3 = 300 (dcs); OLAP: PG9.0–19 Beta 3 = 300 (dcs); CRIT: PG9.0–19 Beta 3 = 300 (dcs); TINY: PG9.0–19 Beta 3 = 300 (dcs). Advice, pending human review — Editorial interpretation, pending human maintainer review: the override appears intended to bound how long a quiet primary can leave its newest WAL unavailable to the archive; confirm it against the current Pigsty templates, hardware fixture, and operational guarantees before publication.

## Common pitfalls {#common-pitfalls}

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

## Related parameters {#related-parameters}

[`archive_mode`](/parameters/archive-mode/) · [`archive_command`](/parameters/archive-command/) · [`archive_library`](/parameters/archive-library/) · [`archive_cleanup_command`](/parameters/archive-cleanup-command/) · [`restore_command`](/parameters/restore-command/) · [`recovery_end_command`](/parameters/recovery-end-command/)

## References {#references}

- [PostgreSQL 19 Beta 3 — archive_timeout](https://www.postgresql.org/docs/19/runtime-config-wal.html#GUC-ARCHIVE-TIMEOUT)
- [PostgreSQL 19 release notes](https://www.postgresql.org/docs/19/release-19.html)
- [Machine-readable GUC export](/data/guc.jsonl)