From 25c847ccfb493d548eb3e9af2a3d88b99fdf2a2d Mon Sep 17 00:00:00 2001 From: Bertrand Drouvot Date: Thu, 22 Oct 2026 04:17:46 +0000 Subject: [PATCH v4 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 operations that may use the ring-based types. Update related documentation to use the strategy names. Author: Bertrand Drouvot Reviewed-by: Sami Imseih Discussion: https://postgr.es/m/auCYYbDyrQEwIsQq@bdtpg --- doc/src/sgml/glossary.sgml | 63 +++++++++++++++++++++++----- doc/src/sgml/tablesample-method.sgml | 2 +- 2 files changed, 54 insertions(+), 11 deletions(-) 100.0% doc/src/sgml/ diff --git a/doc/src/sgml/glossary.sgml b/doc/src/sgml/glossary.sgml index d28a3729188..223f90076db 100644 --- a/doc/src/sgml/glossary.sgml +++ b/doc/src/sgml/glossary.sgml @@ -315,13 +315,14 @@ Some operations will access a large number of - pages. A - Buffer Access Strategy helps to prevent these - operations from evicting too many pages from + pages. Using a + strategy ring helps to prevent these operations from evicting too many + pages from shared buffers. - A Buffer Access Strategy sets up references to a limited number of + Except for normal, each Buffer Access Strategy sets up + references to a limited number of shared buffers and reuses them circularly. When the operation requires a new page, a victim buffer is chosen from the buffers in the strategy ring, which may require @@ -329,12 +330,54 @@ 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 the normal clock-sweep buffer replacement policy without a + strategy ring. + + + + + bulkread + + + Uses a strategy ring for operations expected to read many pages with + little reuse. It may be used by large sequential scans and commands + such as ALTER TABLE, + CREATE DATABASE, CREATE INDEX, + and CLUSTER. + + + + + bulkwrite + + + Uses a strategy ring for operations that write many pages. It may be + used by COPY FROM, + CREATE TABLE AS SELECT, + ALTER TABLE, and + CREATE DATABASE. + + + + + 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/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