{"Entry":{"collection":"guc","key":"archive_timeout","name":"archive_timeout","aliases":[],"metadata":{"baseline":false,"boot_human":"Not specified","boot_val":null,"category":"Write-Ahead Log / Archiving","category_zh":"","changed_in":["10","15","18"],"changes":[{"documentation_changed":false,"fields":{},"from":"8.1","status":"added","to":"8.2"},{"documentation_changed":true,"fields":{},"from":"8.4","status":"changed","to":"9.0"},{"documentation_changed":true,"fields":{},"from":"9.0","status":"changed","to":"9.1"},{"documentation_changed":true,"fields":{"short_desc":{"from":"Forces a switch to the next xlog file if a new file has not been started within N seconds.","to":"Forces a switch to the next WAL file if a new file has not been started within N seconds."}},"from":"9.6","status":"changed","to":"10"},{"documentation_changed":true,"fields":{},"from":"11","status":"changed","to":"12"},{"documentation_changed":true,"fields":{},"from":"13","status":"changed","to":"14"},{"documentation_changed":true,"fields":{"short_desc":{"from":"Forces a switch to the next WAL file if a new file has not been started within N seconds.","to":"Sets the amount of time to wait before forcing a switch to the next WAL file."}},"from":"14","status":"changed","to":"15"},{"documentation_changed":false,"fields":{"extra_desc":{"from":null,"to":"0 disables the timeout."}},"from":"17","status":"changed","to":"18"},{"documentation_changed":true,"fields":{},"from":"18","status":"changed","to":"19"}],"content_hash":"c3d330eefdc1ab861ab3e4e8690bd5d6a965ff169e79af8b2c19856e61984b34","context":"","default_changed_in":[],"default_history":[{"from":"9.0","to":"19","value":"0 s"}],"editorial":{"advice":{"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."},"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."],"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."],"references":[{"title":"PostgreSQL 19 Beta 4: archive_timeout","url":"https://www.postgresql.org/docs/19/runtime-config-wal.html#GUC-ARCHIVE-TIMEOUT"},{"title":"PostgreSQL 19 release notes","url":"https://www.postgresql.org/docs/19/release-19.html"}],"related":["archive_mode","archive_command","archive_library","archive_cleanup_command","restore_command","recovery_end_command"],"summary":"archive_timeout — Sets the amount of time to wait before forcing a switch to the next WAL file. Observed in PG9.0–19 Beta 4; its last measured boot default is 0 s in PG19 Beta 4, with sighup context. This is a beta-snapshot fact and can change before PostgreSQL 19 GA."},"enumvals":[],"first_version":"8.2","group":"Write-Ahead Log","group_slug":"wal","imported_at":"2026-09-27T17:57:30.765953+08:00","intro_commit":{},"key":"archive_timeout","last_version":"20","max_val":"","min_val":"","name":"archive_timeout","position":12,"present_in":["8.2","8.3","8.4","9.0","9.1","9.2","9.3","9.4","9.5","9.6","10","11","12","13","14","15","16","17","18","19","20"],"short_desc":"The archive_command or archive_library is only invoked for completed WAL segments.","short_desc_zh":"","source_rev":"english-manuals:e48db6971947ded6631663463f9732e29931577ac737766689270a4c3d40869e","unit":"","vartype":"integer"}},"Definition":{"Collection":"guc","Key":"archive_timeout","SourceDatabase":"center","Version":"18","SourceTable":"guc","SourceKey":"archive_timeout","SourceRevision":"english-manuals:e48db6971947ded6631663463f9732e29931577ac737766689270a4c3d40869e","Facts":{"boot_val":"0","category":"Write-Ahead Log / Archiving","context":"sighup","description":"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.","doc":{"anchor":"GUC-ARCHIVE-TIMEOUT","file":"runtime-config-wal.html","lang":"en","sha256":"d2646404a06e8f7ac655204b4f28c049ae8f3fd4f2272db080fcefa2c4af0763","slug":"18"},"documented":true,"enumvals":null,"extra_desc":"0 disables the timeout.","lang":"en","max_val":"1073741823","metadata_version":"18","min_val":"0","name":"archive_timeout","short_desc":"Sets the amount of time to wait before forcing a switch to the next WAL file.","source":"pg-settings-source-snapshot","unit":"s","vartype":"integer"},"ManualEvidence":{"doc":{"anchor":"GUC-ARCHIVE-TIMEOUT","file":"runtime-config-wal.html","lang":"en","sha256":"d2646404a06e8f7ac655204b4f28c049ae8f3fd4f2272db080fcefa2c4af0763","slug":"18"}},"MeasuredEvidence":{"metadata_version":"18"}},"Text":{"Collection":"guc","Key":"archive_timeout","SourceDatabase":"pgweb","Version":"18","Locale":"zh-Hans","Title":"archive_timeout","Summary":"","BodyHTML":"\u003cp\u003e\u003ca href=\"/docs/18/runtime-config-wal.html#GUC-ARCHIVE-COMMAND\" rel=\"nofollow\"\u003earchive_command\u003c/a\u003e或\u003ca href=\"/docs/18/runtime-config-wal.html#GUC-ARCHIVE-LIBRARY\" rel=\"nofollow\"\u003earchive_library\u003c/a\u003e只针对已完成的 WAL 段调用。因此，如果您的服务器生成的WAL流量较少（或者有些时段生成的 WAL 流量较少），在事务完成和安全记录到归档存储之间可能会有很长的延迟。为了限制未归档数据的年龄，您可以将\u003ccode\u003earchive_timeout\u003c/code\u003e设置为强制服务器定期切换到新的WAL段文件。当此参数大于零时，只要自上次段文件切换以来经过了这段时间，并且存在任何数据库活动，包括单个检查点（如果没有数据库活动，则跳过检查点），服务器将切换到新的段文件。请注意，由于强制切换而提前关闭的归档文件仍然与完全填满的文件长度相同。因此，使用非常短的\u003ccode\u003earchive_timeout\u003c/code\u003e是不明智的，它会使您的归档存储膨胀。通常，将\u003ccode\u003earchive_timeout\u003c/code\u003e设置为一分钟左右是合理的。如果您希望数据比这更快地从主库复制出来，您应该考虑使用流复制而不是归档。如果未指定单位，则将此值视为秒。此参数只能在\u003ccode\u003epostgresql.conf\u003c/code\u003e文件或服务器命令行中设置。\u003c/p\u003e","SourceRevision":"2026-09-11@29c86d9","ContentHash":"d9b5596c739851811ba0cd274357a6a305010b9d26db060eced21b936e22fe14","Payload":{"carried_from":"","carry_reason":"","doc_html":"\u003cp\u003e\u003ca href=\"/docs/18/runtime-config-wal.html#GUC-ARCHIVE-COMMAND\"\u003earchive_command\u003c/a\u003e或\u003ca href=\"/docs/18/runtime-config-wal.html#GUC-ARCHIVE-LIBRARY\"\u003earchive_library\u003c/a\u003e只针对已完成的 WAL 段调用。因此，如果您的服务器生成的WAL流量较少（或者有些时段生成的 WAL 流量较少），在事务完成和安全记录到归档存储之间可能会有很长的延迟。为了限制未归档数据的年龄，您可以将\u003ccode class=\"varname\"\u003earchive_timeout\u003c/code\u003e设置为强制服务器定期切换到新的WAL段文件。当此参数大于零时，只要自上次段文件切换以来经过了这段时间，并且存在任何数据库活动，包括单个检查点（如果没有数据库活动，则跳过检查点），服务器将切换到新的段文件。请注意，由于强制切换而提前关闭的归档文件仍然与完全填满的文件长度相同。因此，使用非常短的\u003ccode class=\"varname\"\u003earchive_timeout\u003c/code\u003e是不明智的，它会使您的归档存储膨胀。通常，将\u003ccode class=\"varname\"\u003earchive_timeout\u003c/code\u003e设置为一分钟左右是合理的。如果您希望数据比这更快地从主库复制出来，您应该考虑使用流复制而不是归档。如果未指定单位，则将此值视为秒。此参数只能在\u003ccode class=\"filename\"\u003epostgresql.conf\u003c/code\u003e文件或服务器命令行中设置。\u003c/p\u003e","doc_same_as":""}},"RequestedLocale":"zh-Hans","Fallback":false,"Versions":["10","11","12","13","14","15","16","17","18","19","20","8.2","8.3","8.4","9.0","9.1","9.2","9.3","9.4","9.5","9.6"],"Locales":["en","zh-Hans"],"Signatures":null,"Spellings":null,"SQLState":null,"Evidence":null}