{"Entry":{"collection":"guc","key":"wal_decode_buffer_size","name":"wal_decode_buffer_size","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"}],"content_hash":"14f825287c922e964017d226b4c0d9279bfab6901884a64e86652076338cac00","context":"","default_changed_in":[],"default_history":[{"from":"15","to":"19","value":"512 KiB"}],"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 wal_decode_buffer_size 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":["Buffer size for reading ahead in the WAL during recovery. The value is fixed when the server starts, so changing it requires a restart.","Recovery scans this far ahead in decoded WAL to discover future block references for prefetch. It is a restart-time memory/lead limit, not a logical-decoding output buffer, and only helps when recovery_prefetch and the storage workload benefit.","Monitor and change wal_decode_buffer_size together with recovery_prefetch, maintenance_io_concurrency, effective_io_concurrency. Validate on the relevant server role and real workload, then use its postmaster context to choose session change, reload, or restart; a historical boot default is not the current effective value."],"pitfalls":["Confusing pg_settings base units with human-readable configuration units.","Benchmarking throughput without a crash-recovery and archive-restore test.","Ignoring interactions with checkpoints, replication slots, or archive failure.","Reloading a restart-context value and assuming it became active."],"references":[{"title":"PostgreSQL 19 Beta 4: wal_decode_buffer_size","url":"https://www.postgresql.org/docs/19/runtime-config-wal.html#GUC-WAL-DECODE-BUFFER-SIZE"},{"title":"PostgreSQL 19 release notes","url":"https://www.postgresql.org/docs/19/release-19.html"}],"related":["recovery_prefetch","maintenance_io_concurrency","effective_io_concurrency","shared_buffers","archive_cleanup_command","archive_command"],"summary":"wal_decode_buffer_size sets the buffer size for reading ahead in the WAL during recovery. It is a postmaster setting present in PG15–18; the latest recorded boot default is 512 KiB."},"enumvals":[],"first_version":"15","group":"Write-Ahead Log","group_slug":"wal","imported_at":"2026-09-27T17:57:32.328888+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":"wal_decode_buffer_size","last_version":"20","max_val":"","min_val":"","name":"wal_decode_buffer_size","position":467,"present_in":["15","16","17","18","19","20"],"short_desc":"A limit on how far ahead the server can look in the WAL, to find blocks to prefetch.","short_desc_zh":"","source_rev":"english-manuals:0204a441e5744b1cd99769ca9d4ae19b018b1956890f569425bf35a63806a421","unit":"","vartype":"integer"}},"Definition":{"Collection":"guc","Key":"wal_decode_buffer_size","SourceDatabase":"center","Version":"18","SourceTable":"guc","SourceKey":"wal_decode_buffer_size","SourceRevision":"english-manuals:0204a441e5744b1cd99769ca9d4ae19b018b1956890f569425bf35a63806a421","Facts":{"boot_val":"524288","category":"Write-Ahead Log / Recovery","context":"postmaster","description":"A limit on how far ahead the server can look in the WAL, to find blocks to prefetch. If this value is specified without units, it is taken as bytes. The default is 512kB. This parameter can only be set at server start.","doc":{"anchor":"GUC-WAL-DECODE-BUFFER-SIZE","file":"runtime-config-wal.html","lang":"en","sha256":"d2646404a06e8f7ac655204b4f28c049ae8f3fd4f2272db080fcefa2c4af0763","slug":"18"},"documented":true,"enumvals":null,"extra_desc":"Maximum distance to read ahead in the WAL to prefetch referenced data blocks.","lang":"en","max_val":"1073741823","metadata_version":"18","min_val":"65536","name":"wal_decode_buffer_size","short_desc":"Buffer size for reading ahead in the WAL during recovery.","source":"pg-settings-source-snapshot","unit":"B","vartype":"integer"},"ManualEvidence":{"doc":{"anchor":"GUC-WAL-DECODE-BUFFER-SIZE","file":"runtime-config-wal.html","lang":"en","sha256":"d2646404a06e8f7ac655204b4f28c049ae8f3fd4f2272db080fcefa2c4af0763","slug":"18"}},"MeasuredEvidence":{"metadata_version":"18"}},"Text":{"Collection":"guc","Key":"wal_decode_buffer_size","SourceDatabase":"center","Version":"18","Locale":"en","Title":"wal_decode_buffer_size","Summary":"A limit on how far ahead the server can look in the WAL, to find blocks to prefetch. If this value is specified without units, it is taken as bytes. The default is 512kB. This parameter can only be set at server start.","BodyHTML":"\u003cp\u003eA limit on how far ahead the server can look in the WAL, to find blocks to prefetch. If this value is specified without units, it is taken as bytes. The default is 512kB. This parameter can only be set at server start.\u003c/p\u003e","SourceRevision":"english-manuals:0204a441e5744b1cd99769ca9d4ae19b018b1956890f569425bf35a63806a421","ContentHash":"8cf84ca72ada64c522c88962377f8efdd8d28b11ff9a1aac4f11919181b09c7f","Payload":{"description":"A limit on how far ahead the server can look in the WAL, to find blocks to prefetch. If this value is specified without units, it is taken as bytes. The default is 512kB. This parameter can only be set at server start."}},"RequestedLocale":"zh-Hans","Fallback":true,"Versions":["15","16","17","18","19","20"],"Locales":["en"],"Signatures":null,"Spellings":null,"SQLState":null,"Evidence":null}