From 156ab405d6bf7a62dca8b77f7c21ac83c4f64180 Mon Sep 17 00:00:00 2001 From: Bertrand Drouvot Date: Thu, 22 Oct 2026 04:17:46 +0000 Subject: [PATCH v3 2/8] Describe buffer access strategy types in the glossary The glossary explains the purpose and mechanics of buffer access strategies, but not the available strategy types. Describe normal, bulkread, bulkwrite, and vacuum, including the kinds of operations that use each ring-based strategy. Use the types in the places that mentions the glossary. Author: Bertrand Drouvot Reviewed-by: Sami Imseih Discussion: https://postgr.es/m/auCYYbDyrQEwIsQq@bdtpg --- doc/src/sgml/config.sgml | 2 ++ doc/src/sgml/glossary.sgml | 49 ++++++++++++++++++++++++---- doc/src/sgml/ref/analyze.sgml | 3 +- doc/src/sgml/ref/vacuum.sgml | 3 +- doc/src/sgml/ref/vacuumdb.sgml | 1 + doc/src/sgml/tablesample-method.sgml | 2 +- 6 files changed, 51 insertions(+), 9 deletions(-) 16.5% doc/src/sgml/ref/ 83.4% doc/src/sgml/ diff --git a/doc/src/sgml/config.sgml b/doc/src/sgml/config.sgml index 289058484ab..9b4f4657b44 100644 --- a/doc/src/sgml/config.sgml +++ b/doc/src/sgml/config.sgml @@ -2130,6 +2130,7 @@ include_dir 'conf.d' Specifies the size of the + vacuum Buffer Access Strategy used by the VACUUM and ANALYZE commands. A setting of 0 will allow the operation @@ -10142,6 +10143,7 @@ COPY postgres_log FROM '/full/path/to/logfile.csv' WITH csv; When the failsafe is triggered, any cost-based delay that is in effect will no longer be applied, further non-essential maintenance tasks (such as index vacuuming) are bypassed, and any + vacuum Buffer Access Strategy in use will be disabled resulting in VACUUM being free to make use of all of diff --git a/doc/src/sgml/glossary.sgml b/doc/src/sgml/glossary.sgml index d28a3729188..890c6998eb2 100644 --- a/doc/src/sgml/glossary.sgml +++ b/doc/src/sgml/glossary.sgml @@ -329,12 +329,49 @@ WAL to permanent storage. - Buffer Access Strategies are used for various operations such as - sequential scans of large tables, VACUUM, - COPY, CREATE TABLE AS SELECT, - ALTER TABLE, CREATE DATABASE, - CREATE INDEX, and CLUSTER. - + The available buffer access strategy types are: + + + + normal + + + Uses ordinary buffer replacement rather than a strategy ring. + + + + + bulkread + + + Uses a strategy ring for operations expected to read many pages with + little reuse, such as large sequential scans. Reusing a limited set of + buffers reduces eviction of unrelated pages from shared buffers. + + + + + bulkwrite + + + Uses a strategy ring for operations that write many pages, such as + COPY FROM and + CREATE TABLE AS SELECT. + + + + + vacuum + + + Uses a strategy ring for maintenance operations such as + VACUUM and ANALYZE. Its size can + be controlled with + . + + + + diff --git a/doc/src/sgml/ref/analyze.sgml b/doc/src/sgml/ref/analyze.sgml index d27c0d9e864..671c5cca8a4 100644 --- a/doc/src/sgml/ref/analyze.sgml +++ b/doc/src/sgml/ref/analyze.sgml @@ -94,10 +94,11 @@ ANALYZE [ ( option [, ...] ) ] [ Specifies the + vacuum Buffer Access Strategy ring buffer size for ANALYZE. This size is used to calculate the number of shared buffers which will be reused as part of - this strategy. 0 disables use of a + this strategy. 0 disables use of a vacuum Buffer Access Strategy. When this option is not specified, ANALYZE uses the value from . Higher settings can diff --git a/doc/src/sgml/ref/vacuum.sgml b/doc/src/sgml/ref/vacuum.sgml index 25234a17baf..78ec7195946 100644 --- a/doc/src/sgml/ref/vacuum.sgml +++ b/doc/src/sgml/ref/vacuum.sgml @@ -314,10 +314,11 @@ VACUUM [ ( option [, ...] ) ] [ Specifies the + vacuum Buffer Access Strategy ring buffer size for VACUUM. This size is used to calculate the number of shared buffers which will be reused as part of - this strategy. 0 disables use of a + this strategy. 0 disables use of a vacuum Buffer Access Strategy. If is also specified, the value is used for both the vacuum and analyze stages. This option can't be used with diff --git a/doc/src/sgml/ref/vacuumdb.sgml b/doc/src/sgml/ref/vacuumdb.sgml index 508c8dfa146..cabc816837c 100644 --- a/doc/src/sgml/ref/vacuumdb.sgml +++ b/doc/src/sgml/ref/vacuumdb.sgml @@ -136,6 +136,7 @@ PostgreSQL documentation Specifies the + vacuum Buffer Access Strategy ring buffer size for a given invocation of vacuumdb. This size is used to calculate the number of shared buffers which will diff --git a/doc/src/sgml/tablesample-method.sgml b/doc/src/sgml/tablesample-method.sgml index c821941b71b..8465005a3d7 100644 --- a/doc/src/sgml/tablesample-method.sgml +++ b/doc/src/sgml/tablesample-method.sgml @@ -202,7 +202,7 @@ BeginSampleScan (SampleScanState *node, This function may adjust the fields node->use_bulkread and node->use_pagemode. If node->use_bulkread is true, which it is by - default, the scan will use a buffer access strategy that encourages + default, the scan will use a bulkread buffer access strategy that encourages recycling buffers after use. It might be reasonable to set this to false if the scan will visit only a small fraction of the table's pages. -- 2.34.1