{"Entry":{"collection":"guc","key":"vacuum_buffer_usage_limit","name":"vacuum_buffer_usage_limit","aliases":[],"metadata":{"baseline":false,"boot_human":"Not specified","boot_val":null,"category":"Resource Usage / Memory","category_zh":"","changed_in":["17"],"changes":[{"documentation_changed":false,"fields":{},"from":"15","status":"added","to":"16"},{"documentation_changed":true,"fields":{"boot_val":{"from":"256","to":"2048"}},"from":"16","status":"changed","to":"17"}],"content_hash":"76e0cb06d79a20e626c40fdb1e3f69d28db8d5572eb20fe825092aa14edd29b5","context":"","default_changed_in":["17"],"default_history":[{"from":"16","to":"16","value":"256 KiB"},{"from":"17","to":"19","value":"2 MiB"}],"editorial":{"advice":{"olap":"Benchmark vacuum_buffer_usage_limit with representative bulk and scan phases. Include sustained throughput, spill/writeback, and interference with other sessions, not only one operation's elapsed time.","oltp":"Change vacuum_buffer_usage_limit only after identifying the corresponding resource bottleneck under concurrency. Budget total memory, I/O, disk, or kernel capacity rather than optimizing one process in isolation.","small":"Keep vacuum_buffer_usage_limit conservative on a small host and prefer the upstream default when evidence is weak. A setting copied from a large server can consume a disproportionate share of resources."},"mechanism":["vacuum_buffer_usage_limit sizes the shared-buffer access-strategy ring used by VACUUM, ANALYZE, and autovacuum. It is not a private memory allocation and does not cap all buffers those operations can ever touch.","A nonzero value is silently capped at one eighth of shared_buffers; zero allows unrestricted shared-buffer use. The ring reduces eviction of unrelated hot pages while permitting repeated reuse during scans.","Larger rings can improve maintenance throughput but can displace more useful cache. VACUUM and ANALYZE can override it per command with BUFFER_USAGE_LIMIT, and the boot default rose from 256kB in PG16 to 2MB in PG17. Its user context permits session- or transaction-local changes; newly performed or newly planned work sees the value."],"pitfalls":["Changing vacuum_buffer_usage_limit without applying its documented unit and configuration context.","Optimizing an isolated benchmark while ignoring concurrent aggregate resource use.","Assuming a configured value guarantees operating-system or storage behavior.","Failing to retest startup, failover, and workload latency after the change."],"references":[{"title":"PostgreSQL 19 Beta 4: vacuum_buffer_usage_limit","url":"https://www.postgresql.org/docs/19/runtime-config-resource.html#GUC-VACUUM-BUFFER-USAGE-LIMIT"},{"title":"PostgreSQL 19 release notes","url":"https://www.postgresql.org/docs/19/release-19.html"}],"related":["shared_buffers","maintenance_work_mem","autovacuum_work_mem","maintenance_io_concurrency","track_io_timing"],"summary":"vacuum_buffer_usage_limit — Sets the buffer pool size for VACUUM, ANALYZE, and autovacuum. Observed in PG16–19 Beta 4; its last measured boot default is 2 MiB in PG19 Beta 4, with user context. This is a beta-snapshot fact and can change before PostgreSQL 19 GA."},"enumvals":[],"first_version":"16","group":"Resource Usage","group_slug":"resource","imported_at":"2026-09-27T17:57:32.262283+08:00","intro_commit":{"authored_at":"2023-04-07T11:40:31+12:00","discussion":["https://postgr.es/m/20230111182720.ejifsclfwymw2reb@awork3.anarazel.de"],"hash":"1cbbee03385763b066ae3961fc61f2cd01a0d0d7","subject":"Add VACUUM/ANALYZE BUFFER_USAGE_LIMIT option","url":"https://git.postgresql.org/gitweb/?p=postgresql.git;a=commit;h=1cbbee03385763b066ae3961fc61f2cd01a0d0d7"},"key":"vacuum_buffer_usage_limit","last_version":"20","max_val":"","min_val":"","name":"vacuum_buffer_usage_limit","position":444,"present_in":["16","17","18","19","20"],"short_desc":"Specifies the size of the Buffer Access Strategy used by the VACUUM and ANALYZE commands.","short_desc_zh":"","source_rev":"english-manuals:6146f68db3251bba0029b91ba856b626fd82157a0e03315c830b3a6d0d5ab00e","unit":"","vartype":"integer"}},"Definition":{"Collection":"guc","Key":"vacuum_buffer_usage_limit","SourceDatabase":"center","Version":"18","SourceTable":"guc","SourceKey":"vacuum_buffer_usage_limit","SourceRevision":"english-manuals:6146f68db3251bba0029b91ba856b626fd82157a0e03315c830b3a6d0d5ab00e","Facts":{"boot_val":"2048","category":"Resource Usage / Memory","context":"user","description":"Specifies the size of the Buffer Access Strategy used by the VACUUM and ANALYZE commands. A setting of 0 will allow the operation to use any number of shared_buffers. Otherwise valid sizes range from 128 kB to 16 GB. If the specified size would exceed 1/8 the size of shared_buffers, the size is silently capped to that value. The default value is 2MB. If this value is specified without units, it is taken as kilobytes. This parameter can be set at any time. It can be overridden for VACUUM and ANALYZE when passing the BUFFER_USAGE_LIMIT option. Higher settings can allow VACUUM and ANALYZE to run more quickly, but having too large a setting may cause too many other useful pages to be evicted from shared buffers.","doc":{"anchor":"GUC-VACUUM-BUFFER-USAGE-LIMIT","file":"runtime-config-resource.html","lang":"en","sha256":"2e207c599f0884dfbe594558c478a2c7c132578981071e980e2015f31dfce28c","slug":"18"},"documented":true,"enumvals":null,"extra_desc":null,"lang":"en","max_val":"16777216","metadata_version":"18","min_val":"0","name":"vacuum_buffer_usage_limit","short_desc":"Sets the buffer pool size for VACUUM, ANALYZE, and autovacuum.","source":"pg-settings-source-snapshot","unit":"kB","vartype":"integer"},"ManualEvidence":{"doc":{"anchor":"GUC-VACUUM-BUFFER-USAGE-LIMIT","file":"runtime-config-resource.html","lang":"en","sha256":"2e207c599f0884dfbe594558c478a2c7c132578981071e980e2015f31dfce28c","slug":"18"}},"MeasuredEvidence":{"metadata_version":"18"}},"Text":{"Collection":"guc","Key":"vacuum_buffer_usage_limit","SourceDatabase":"pgweb","Version":"18","Locale":"zh-Hans","Title":"vacuum_buffer_usage_limit","Summary":"","BodyHTML":"\u003cp\u003e指定 \u003ccode\u003eVACUUM\u003c/code\u003e 和 \u003ccode\u003eANALYZE\u003c/code\u003e 命令使用的\u003ca href=\"/docs/18/glossary.html#GLOSSARY-BUFFER-ACCESS-STRATEGY\" rel=\"nofollow\"\u003e\u003c/a\u003e\u003ca href=\"/docs/18/glossary.html#GLOSSARY-BUFFER-ACCESS-STRATEGY\" title=\"缓冲区访问策略\" rel=\"nofollow\"\u003e缓冲区访问策略\u003c/a\u003e的大小。设为 \u003ccode\u003e0\u003c/code\u003e 时，允许操作使用任意数量的 \u003ccode\u003eshared_buffers\u003c/code\u003e 缓冲区。否则，有效大小范围为 \u003ccode\u003e128 kB\u003c/code\u003e 至 \u003ccode\u003e16 GB\u003c/code\u003e。如果指定的大小超过 \u003ccode\u003eshared_buffers\u003c/code\u003e 大小的 1/8，则会在不提示的情况下限制为该值。默认值为 \u003ccode\u003e2MB\u003c/code\u003e。如果未指定单位，则以千字节为单位。此参数可以随时设置。在执行\u003ca href=\"/docs/18/sql-vacuum.html\" title=\"VACUUM\" rel=\"nofollow\"\u003e\u003cspan\u003eVACUUM\u003c/span\u003e\u003c/a\u003e和\u003ca href=\"/docs/18/sql-analyze.html\" title=\"ANALYZE\" rel=\"nofollow\"\u003e\u003cspan\u003eANALYZE\u003c/span\u003e\u003c/a\u003e时，可以通过 \u003ccode\u003eBUFFER_USAGE_LIMIT\u003c/code\u003e 选项覆盖此设置。较大的设置可能使 \u003ccode\u003eVACUUM\u003c/code\u003e 和 \u003ccode\u003eANALYZE\u003c/code\u003e 运行得更快，但设置过大可能会将过多其他有用页面逐出共享缓冲区。\u003c/p\u003e","SourceRevision":"2026-09-11@29c86d9","ContentHash":"34006aa44fd1022b4882113aa5f1dffbafd7f5b67294a64a718ea682ca0125e4","Payload":{"carried_from":"","carry_reason":"","doc_html":"\u003cp\u003e指定 \u003ccode class=\"command\"\u003eVACUUM\u003c/code\u003e 和 \u003ccode class=\"command\"\u003eANALYZE\u003c/code\u003e 命令使用的\u003ca href=\"/docs/18/glossary.html#GLOSSARY-BUFFER-ACCESS-STRATEGY\"\u003e\u003c/a\u003e\u003ca href=\"/docs/18/glossary.html#GLOSSARY-BUFFER-ACCESS-STRATEGY\" title=\"缓冲区访问策略\"\u003e缓冲区访问策略\u003c/a\u003e的大小。设为 \u003ccode class=\"literal\"\u003e0\u003c/code\u003e 时，允许操作使用任意数量的 \u003ccode class=\"varname\"\u003eshared_buffers\u003c/code\u003e 缓冲区。否则，有效大小范围为 \u003ccode class=\"literal\"\u003e128 kB\u003c/code\u003e 至 \u003ccode class=\"literal\"\u003e16 GB\u003c/code\u003e。如果指定的大小超过 \u003ccode class=\"varname\"\u003eshared_buffers\u003c/code\u003e 大小的 1/8，则会在不提示的情况下限制为该值。默认值为 \u003ccode class=\"literal\"\u003e2MB\u003c/code\u003e。如果未指定单位，则以千字节为单位。此参数可以随时设置。在执行\u003ca href=\"/docs/18/sql-vacuum.html\" title=\"VACUUM\"\u003e\u003cspan class=\"refentrytitle\"\u003eVACUUM\u003c/span\u003e\u003c/a\u003e和\u003ca href=\"/docs/18/sql-analyze.html\" title=\"ANALYZE\"\u003e\u003cspan class=\"refentrytitle\"\u003eANALYZE\u003c/span\u003e\u003c/a\u003e时，可以通过 \u003ccode class=\"option\"\u003eBUFFER_USAGE_LIMIT\u003c/code\u003e 选项覆盖此设置。较大的设置可能使 \u003ccode class=\"command\"\u003eVACUUM\u003c/code\u003e 和 \u003ccode class=\"command\"\u003eANALYZE\u003c/code\u003e 运行得更快，但设置过大可能会将过多其他有用页面逐出共享缓冲区。\u003c/p\u003e","doc_same_as":""}},"RequestedLocale":"zh-Hans","Fallback":false,"Versions":["16","17","18","19","20"],"Locales":["en","zh-Hans"],"Signatures":null,"Spellings":null,"SQLState":null,"Evidence":null}