From 2722bd10c1c4076df8bab63673a5034221631446 Mon Sep 17 00:00:00 2001 From: Bertrand Drouvot Date: Thu, 22 Oct 2026 04:17:46 +0000 Subject: [PATCH v1 2/5] 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: Discussion: https://postgr.es/m/ --- 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.7% doc/src/sgml/ref/ 83.2% doc/src/sgml/ diff --git a/doc/src/sgml/config.sgml b/doc/src/sgml/config.sgml index f7db2995c3e..8852549e97b 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 @@ -10133,6 +10134,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..66413c838f6 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 strategies are: + + + + normal + + + Uses ordinary buffer replacement without 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 the displacement of unrelated cached data. + + + + + 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 3c85846df26..3e3f2d30ec9 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