{"Entry":{"collection":"guc","key":"recovery_prefetch","name":"recovery_prefetch","aliases":[],"metadata":{"baseline":false,"boot_human":"Not specified","boot_val":null,"category":"Write-Ahead Log / Recovery","category_zh":"","changed_in":[],"changes":[{"documentation_changed":false,"fields":{},"from":"14","status":"added","to":"15"},{"documentation_changed":true,"fields":{},"from":"17","status":"changed","to":"18"}],"content_hash":"de2211ba02170080fb45e2cd614763b9787ba36bf4f6f047b566cc7552cf4302","context":"","default_changed_in":[],"default_history":[{"from":"15","to":"19","value":"try"}],"editorial":{"advice":{"olap":"Large data with slow random reads may benefit more, but excess prefetch competes with query I/O and cache. Test crash recovery and a query-serving standby separately.","oltp":"Tune recovery_prefetch with recovery/standby catch-up benchmarks on production-like storage while observing replay I/O wait, cache behavior, and maintenance_io_concurrency. Keep the default without measured benefit.","small":"The default is usually sufficient. Do not spend scarce memory or I/O queue depth on a larger look-ahead window unless a recovery-time objective is demonstrably missed."},"mechanism":["Prefetch referenced blocks during recovery. A configuration reload applies a new value; existing work already in flight is not retroactively changed.","During recovery, PostgreSQL can issue read-ahead advice for blocks identified by WAL before replay needs them. try enables it only when the operating system supports the required advice; wal_decode_buffer_size and maintenance_io_concurrency bound how far and how much it can prefetch.","Monitor and change recovery_prefetch together with wal_decode_buffer_size, maintenance_io_concurrency, effective_io_concurrency. 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":["Assuming try always enables prefetch even when the operating system lacks the required read-ahead advice.","Increasing look-ahead without considering wal_decode_buffer_size and maintenance_io_concurrency.","Letting recovery prefetch compete with queries on a hot standby for cache and I/O queue depth.","Benchmarking sequential recovery only, where block prefetch may provide little benefit."],"references":[{"title":"PostgreSQL 19 Beta 4: recovery_prefetch","url":"https://www.postgresql.org/docs/19/runtime-config-wal.html#GUC-RECOVERY-PREFETCH"},{"title":"PostgreSQL 19 release notes","url":"https://www.postgresql.org/docs/19/release-19.html"}],"related":["wal_decode_buffer_size","maintenance_io_concurrency","effective_io_concurrency","shared_buffers","archive_cleanup_command","archive_command"],"summary":"recovery_prefetch prefetches referenced blocks during recovery. It is a sighup setting present in PG15–18; the latest recorded boot default is try."},"enumvals":[],"first_version":"15","group":"Write-Ahead Log","group_slug":"wal","imported_at":"2026-09-27T17:57:31.869566+08:00","intro_commit":{"authored_at":"2021-04-08T23:03:43+12:00","discussion":["https://postgr.es/m/CA%2BhUKGJ4VJN8ttxScUFM8dOKX0BrBiboo5uz1cq%3DAovOddfHpA%40mail.gmail.com"],"hash":"1d257577e08d3e598011d6850fd1025858de8c8c","subject":"Optionally prefetch referenced data in recovery.","url":"https://git.postgresql.org/gitweb/?p=postgresql.git;a=commit;h=1d257577e08d3e598011d6850fd1025858de8c8c"},"key":"recovery_prefetch","last_version":"20","max_val":"","min_val":"","name":"recovery_prefetch","position":324,"present_in":["15","16","17","18","19","20"],"short_desc":"Whether to try to prefetch blocks that are referenced in the WAL that are not yet in the buffer pool, during recovery.","short_desc_zh":"","source_rev":"english-manuals:96e99942b6005ccaf37c09bca9fe51fb86b12d9615b881d4e2286c3850c020d1","unit":"","vartype":"enum"}},"Definition":{"Collection":"guc","Key":"recovery_prefetch","SourceDatabase":"center","Version":"18","SourceTable":"guc","SourceKey":"recovery_prefetch","SourceRevision":"english-manuals:96e99942b6005ccaf37c09bca9fe51fb86b12d9615b881d4e2286c3850c020d1","Facts":{"boot_val":"try","category":"Write-Ahead Log / Recovery","context":"sighup","description":"Whether to try to prefetch blocks that are referenced in the WAL that are not yet in the buffer pool, during recovery. Valid values are off, on and try (the default). The setting try enables prefetching only if the operating system provides support for issuing read-ahead advice. Prefetching blocks that will soon be needed can reduce I/O wait times during recovery with some workloads. See also the wal_decode_buffer_size and maintenance_io_concurrency settings, which limit prefetching activity.","doc":{"anchor":"GUC-RECOVERY-PREFETCH","file":"runtime-config-wal.html","lang":"en","sha256":"d2646404a06e8f7ac655204b4f28c049ae8f3fd4f2272db080fcefa2c4af0763","slug":"18"},"documented":true,"enumvals":["off","on","try"],"extra_desc":"Look ahead in the WAL to find references to uncached data.","lang":"en","max_val":null,"metadata_version":"18","min_val":null,"name":"recovery_prefetch","short_desc":"Prefetch referenced blocks during recovery.","source":"pg-settings-source-snapshot","unit":null,"vartype":"enum"},"ManualEvidence":{"doc":{"anchor":"GUC-RECOVERY-PREFETCH","file":"runtime-config-wal.html","lang":"en","sha256":"d2646404a06e8f7ac655204b4f28c049ae8f3fd4f2272db080fcefa2c4af0763","slug":"18"}},"MeasuredEvidence":{"metadata_version":"18"}},"Text":{"Collection":"guc","Key":"recovery_prefetch","SourceDatabase":"pgweb","Version":"18","Locale":"zh-Hans","Title":"recovery_prefetch","Summary":"","BodyHTML":"\u003cp\u003e是否在恢复期间尝试预取 WAL 中引用但尚未在缓冲池中的块。有效值为\u003ccode\u003eoff\u003c/code\u003e、\u003ccode\u003eon\u003c/code\u003e和\u003ccode\u003etry\u003c/code\u003e（默认值）。\u003ccode\u003etry\u003c/code\u003e设置仅在操作系统支持发出预读建议时启用预取。\u003c/p\u003e\u003cp\u003e预取即将需要的块可以减少某些工作负载下恢复期间的I/O等待时间。另请参阅\u003ca href=\"/docs/18/runtime-config-wal.html#GUC-WAL-DECODE-BUFFER-SIZE\" rel=\"nofollow\"\u003ewal_decode_buffer_size\u003c/a\u003e和\u003ca href=\"/docs/18/runtime-config-resource.html#GUC-MAINTENANCE-IO-CONCURRENCY\" rel=\"nofollow\"\u003emaintenance_io_concurrency\u003c/a\u003e设置，限制预取活动。\u003c/p\u003e","SourceRevision":"2026-09-11@29c86d9","ContentHash":"7d545acc3c6192813faa10d4a4ff07f70643624c18d8ef8ae4e512fcdfb4d593","Payload":{"carried_from":"","carry_reason":"","doc_html":"\u003cp\u003e是否在恢复期间尝试预取 WAL 中引用但尚未在缓冲池中的块。有效值为\u003ccode class=\"literal\"\u003eoff\u003c/code\u003e、\u003ccode class=\"literal\"\u003eon\u003c/code\u003e和\u003ccode class=\"literal\"\u003etry\u003c/code\u003e（默认值）。\u003ccode class=\"literal\"\u003etry\u003c/code\u003e设置仅在操作系统支持发出预读建议时启用预取。\u003c/p\u003e\u003cp\u003e预取即将需要的块可以减少某些工作负载下恢复期间的I/O等待时间。另请参阅\u003ca href=\"/docs/18/runtime-config-wal.html#GUC-WAL-DECODE-BUFFER-SIZE\"\u003ewal_decode_buffer_size\u003c/a\u003e和\u003ca href=\"/docs/18/runtime-config-resource.html#GUC-MAINTENANCE-IO-CONCURRENCY\"\u003emaintenance_io_concurrency\u003c/a\u003e设置，限制预取活动。\u003c/p\u003e","doc_same_as":""}},"RequestedLocale":"zh-Hans","Fallback":false,"Versions":["15","16","17","18","19","20"],"Locales":["en","zh-Hans"],"Signatures":null,"Spellings":null,"SQLState":null,"Evidence":null}