{"Entry":{"collection":"guc","key":"wal_buffers","name":"wal_buffers","aliases":[],"metadata":{"baseline":true,"boot_human":"Not specified","boot_val":null,"category":"Write-Ahead Log / Settings","category_zh":"","changed_in":["9.1","17","18"],"changes":[{"documentation_changed":true,"fields":{},"from":"7.4","status":"changed","to":"8.0"},{"documentation_changed":true,"fields":{},"from":"8.0","status":"changed","to":"8.1"},{"documentation_changed":true,"fields":{},"from":"8.1","status":"changed","to":"8.2"},{"documentation_changed":true,"fields":{},"from":"8.2","status":"changed","to":"8.3"},{"documentation_changed":true,"fields":{"boot_val":{"from":"8","to":"-1"},"min_val":{"from":"4","to":"-1"}},"from":"9.0","status":"changed","to":"9.1"},{"documentation_changed":true,"fields":{},"from":"9.2","status":"changed","to":"9.3"},{"documentation_changed":true,"fields":{},"from":"11","status":"changed","to":"12"},{"documentation_changed":false,"fields":{"extra_desc":{"from":null,"to":"Specify -1 to have this value determined as a fraction of shared_buffers."}},"from":"16","status":"changed","to":"17"},{"documentation_changed":false,"fields":{"extra_desc":{"from":"Specify -1 to have this value determined as a fraction of shared_buffers.","to":"-1 means use a fraction of \"shared_buffers\"."}},"from":"17","status":"changed","to":"18"}],"content_hash":"73d0c18928869826cf01abc6a92785a4cf9f1a66c392b321fe57ed9dd29b0161","context":"","default_changed_in":["9.1"],"default_history":[{"from":"9.0","to":"9.0","value":"64 KiB (8 × 8kB)"},{"from":"9.1","to":"19","value":"-1 8kB"}],"editorial":{"advice":{"olap":"Provision WAL, archive bandwidth, and recovery I/O for bulk-load peaks. Coordinate load pacing and checkpoints when reducing spikes; never break the recovery chain for throughput.","oltp":"Establish durability and recovery objectives first, then tune wal_buffers from WAL rate, flush latency, checkpoints, and peak pg_wal usage. Validate every change with crash/recovery and archive monitoring.","small":"Start from safe defaults and set explicit alerts for limited disk capacity. Do not disable durability or break the recovery chain merely to save modest I/O."},"mechanism":["Sets the number of disk-page buffers in shared memory for WAL. The value is fixed when the server starts, so changing it requires a restart.","The automatic -1 value chooses about 1/32 of shared_buffers, bounded below and by one WAL segment. The buffer absorbs WAL records before writes; too little can add WALWrite pressure during bursts, while oversized allocation consumes startup shared memory without replacing durable flushes.","Monitor and change wal_buffers together with fsync, full_page_writes, wal_sync_method. 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":["Reading -1 as a negative allocation rather than automatic sizing.","Forgetting that the automatic choice is based on shared_buffers and capped at one WAL segment.","Reading an unqualified positive value as bytes rather than WAL blocks; very small positives are raised to the minimum.","Allocating a large manual buffer without evidence of WALInsert/WALWrite pressure.","Expecting more WAL buffers to replace durable flushes or improve a storage-bound WALSync path."],"references":[{"title":"PostgreSQL 19 Beta 4: wal_buffers","url":"https://www.postgresql.org/docs/19/runtime-config-wal.html#GUC-WAL-BUFFERS"},{"title":"PostgreSQL 19 release notes","url":"https://www.postgresql.org/docs/19/release-19.html"}],"related":["fsync","full_page_writes","wal_sync_method","synchronous_commit","wal_writer_delay","wal_writer_flush_after"],"summary":"wal_buffers — Sets the number of disk-page buffers in shared memory for WAL. Observed in PG9.0–19 Beta 4; its last measured boot default is -1 8kB in PG19 Beta 4, with postmaster context. This is a beta-snapshot fact and can change before PostgreSQL 19 GA."},"enumvals":[],"first_version":"7.4","group":"Write-Ahead Log","group_slug":"wal","imported_at":"2026-09-27T17:57:32.31707+08:00","intro_commit":{},"key":"wal_buffers","last_version":"20","max_val":"","min_val":"","name":"wal_buffers","position":463,"present_in":["7.4","8.0","8.1","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 amount of shared memory used for WAL data that has not yet been written to disk.","short_desc_zh":"","source_rev":"english-manuals:ed3411a871a8384bbaf8a77f87da8a08e0069767c18992cf5c04a2e5f8c54dfa","unit":"","vartype":"integer"}},"Definition":{"Collection":"guc","Key":"wal_buffers","SourceDatabase":"center","Version":"18","SourceTable":"guc","SourceKey":"wal_buffers","SourceRevision":"english-manuals:ed3411a871a8384bbaf8a77f87da8a08e0069767c18992cf5c04a2e5f8c54dfa","Facts":{"boot_val":"-1","category":"Write-Ahead Log / Settings","context":"postmaster","description":"The amount of shared memory used for WAL data that has not yet been written to disk. The default setting of -1 selects a size equal to 1/32nd (about 3%) of shared_buffers, but not less than 64kB nor more than the size of one WAL segment, typically 16MB. This value can be set manually if the automatic choice is too large or too small, but any positive value less than 32kB will be treated as 32kB. If this value is specified without units, it is taken as WAL blocks, that is XLOG_BLCKSZ bytes, typically 8kB. This parameter can only be set at server start. The contents of the WAL buffers are written out to disk at every transaction commit, so extremely large values are unlikely to provide a significant benefit. However, setting this value to at least a few megabytes can improve write performance on a busy server where many clients are committing at once. The auto-tuning selected by the default setting of -1 should give reasonable results in most cases.","doc":{"anchor":"GUC-WAL-BUFFERS","file":"runtime-config-wal.html","lang":"en","sha256":"d2646404a06e8f7ac655204b4f28c049ae8f3fd4f2272db080fcefa2c4af0763","slug":"18"},"documented":true,"enumvals":null,"extra_desc":"-1 means use a fraction of \"shared_buffers\".","lang":"en","max_val":"262143","metadata_version":"18","min_val":"-1","name":"wal_buffers","short_desc":"Sets the number of disk-page buffers in shared memory for WAL.","source":"pg-settings-source-snapshot","unit":"8kB","vartype":"integer"},"ManualEvidence":{"doc":{"anchor":"GUC-WAL-BUFFERS","file":"runtime-config-wal.html","lang":"en","sha256":"d2646404a06e8f7ac655204b4f28c049ae8f3fd4f2272db080fcefa2c4af0763","slug":"18"}},"MeasuredEvidence":{"metadata_version":"18"}},"Text":{"Collection":"guc","Key":"wal_buffers","SourceDatabase":"pgweb","Version":"18","Locale":"zh-Hans","Title":"wal_buffers","Summary":"","BodyHTML":"\u003cp\u003e用于还未写入磁盘的 WAL 数据的共享内存量。默认值 -1 选择等于\u003ca href=\"/docs/18/runtime-config-resource.html#GUC-SHARED-BUFFERS\" rel=\"nofollow\"\u003eshared_buffers\u003c/a\u003e的 1/32 的尺寸（大约3%），但是不小于\u003ccode\u003e64kB\u003c/code\u003e也不大于 WAL 段的尺寸（通常为\u003ccode\u003e16MB\u003c/code\u003e）。如果自动的选择太大或太小可以手工设置该值，但是任何小于\u003ccode\u003e32kB\u003c/code\u003e的正值都将被当作\u003ccode\u003e32kB\u003c/code\u003e。如果指定值时没有单位，则以WAL块作为单位，即为 \u003ccode\u003eXLOG_BLCKSZ\u003c/code\u003e 字节，通常为8kB。这个参数只能在服务器启动时设置。\u003c/p\u003e\u003cp\u003e在每次事务提交时，WAL 缓冲区的内容被写出到磁盘，因此极大的值不太可能带来显著收益。不过，把这个值设置为至少几个兆字节可以在一个繁忙的服务器（其中很多客户端会在同一时间提交）上提高写性能。由默认设置 -1 选择的自动调节将在大部分情况下得到合理的结果。\u003c/p\u003e","SourceRevision":"2026-09-11@29c86d9","ContentHash":"2bdff5922c1392e805a25c20e43cd72babee7215e439bcce20a317b1c98b08eb","Payload":{"carried_from":"","carry_reason":"","doc_html":"\u003cp\u003e用于还未写入磁盘的 WAL 数据的共享内存量。默认值 -1 选择等于\u003ca href=\"/docs/18/runtime-config-resource.html#GUC-SHARED-BUFFERS\"\u003eshared_buffers\u003c/a\u003e的 1/32 的尺寸（大约3%），但是不小于\u003ccode class=\"literal\"\u003e64kB\u003c/code\u003e也不大于 WAL 段的尺寸（通常为\u003ccode class=\"literal\"\u003e16MB\u003c/code\u003e）。如果自动的选择太大或太小可以手工设置该值，但是任何小于\u003ccode class=\"literal\"\u003e32kB\u003c/code\u003e的正值都将被当作\u003ccode class=\"literal\"\u003e32kB\u003c/code\u003e。如果指定值时没有单位，则以WAL块作为单位，即为 \u003ccode class=\"symbol\"\u003eXLOG_BLCKSZ\u003c/code\u003e 字节，通常为8kB。这个参数只能在服务器启动时设置。\u003c/p\u003e\u003cp\u003e在每次事务提交时，WAL 缓冲区的内容被写出到磁盘，因此极大的值不太可能带来显著收益。不过，把这个值设置为至少几个兆字节可以在一个繁忙的服务器（其中很多客户端会在同一时间提交）上提高写性能。由默认设置 -1 选择的自动调节将在大部分情况下得到合理的结果。\u003c/p\u003e","doc_same_as":""}},"RequestedLocale":"zh-Hans","Fallback":false,"Versions":["10","11","12","13","14","15","16","17","18","19","20","7.4","8.0","8.1","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}