From c0235013c13b0adc9e7f1998ff5700e26ecdbd1f Mon Sep 17 00:00:00 2001 From: David Rowley Date: Sun, 16 Apr 2023 12:05:34 +1200 Subject: [PATCH] Improve VACUUM/ANALYZE BUFFER_USAGE_LIMIT docs This addresses various deficiencies in the documentation for VACUUM and ANALYZE's BUFFER_USEAGE_LIMIT docs. Here we declare "size" in the syntax synopsis for VACUUM and ANALYZE's BUFFER_USAGE_LIMIT option and then define exactly what values can be specified for it in the section for that below. Also, fix the incorrect ordering of vacuumdb options both in the documents and in vacuumdb's --help output. These should be in alphabetical order. In passing also add the minimum/maximum range for the BUFFER_USAGE_LIMIT option. These will also serve as example values that can be modified and used. Reported-by: Peter Eisentraut Discussion: https://postgr.es/m/16845cb1-b228-e157-f293-5892bced9253@enterprisedb.com --- doc/src/sgml/ref/analyze.sgml | 18 ++++++++++++++++-- doc/src/sgml/ref/vacuum.sgml | 18 ++++++++++++++++-- doc/src/sgml/ref/vacuumdb.sgml | 26 +++++++++++++------------- src/bin/scripts/vacuumdb.c | 2 +- 4 files changed, 46 insertions(+), 18 deletions(-) diff --git a/doc/src/sgml/ref/analyze.sgml b/doc/src/sgml/ref/analyze.sgml index 94e30f1ce7..20c6f9939f 100644 --- a/doc/src/sgml/ref/analyze.sgml +++ b/doc/src/sgml/ref/analyze.sgml @@ -28,7 +28,7 @@ ANALYZE [ VERBOSE ] [ table_and_columnsboolean ] SKIP_LOCKED [ boolean ] - BUFFER_USAGE_LIMIT [ string ] + BUFFER_USAGE_LIMIT [ size ] and table_and_columns is: @@ -110,7 +110,8 @@ ANALYZE [ VERBOSE ] [ table_and_columns. Higher settings can allow ANALYZE to run more quickly, but having too large a setting may cause too many other useful pages to be evicted from - shared buffers. + shared buffers. The minimum value is 128 kB and the + maximum value is 16 GB. @@ -129,6 +130,19 @@ ANALYZE [ VERBOSE ] [ table_and_columns + + size + + + Specifies an amount of memory in kilobytes. Sizes may also be specified + as a string containing the numerical size followed by any one of the + following memory units: kB (kilobytes), + MB (megabytes), GB (gigabytes), or + TB (terabytes). + + + + table_name diff --git a/doc/src/sgml/ref/vacuum.sgml b/doc/src/sgml/ref/vacuum.sgml index dd0fbb8cb7..57bc4c23ec 100644 --- a/doc/src/sgml/ref/vacuum.sgml +++ b/doc/src/sgml/ref/vacuum.sgml @@ -39,7 +39,7 @@ VACUUM [ FULL ] [ FREEZE ] [ VERBOSE ] [ ANALYZE ] [ integer SKIP_DATABASE_STATS [ boolean ] ONLY_DATABASE_STATS [ boolean ] - BUFFER_USAGE_LIMIT [ string ] + BUFFER_USAGE_LIMIT [ size ] and table_and_columns is: @@ -364,7 +364,8 @@ VACUUM [ FULL ] [ FREEZE ] [ VERBOSE ] [ ANALYZE ] [ . Higher settings can allow VACUUM to run more quickly, but having too large a setting may cause too many other useful pages to be evicted from - shared buffers. + shared buffers. The minimum value is 128 kB and the + maximum value is 16 GB. @@ -392,6 +393,19 @@ VACUUM [ FULL ] [ FREEZE ] [ VERBOSE ] [ ANALYZE ] [ size + + + Specifies an amount of memory in kilobytes. Sizes may also be specified + as a string containing the numerical size followed by any one of the + following memory units: kB (kilobytes), + MB (megabytes), GB (gigabytes), or + TB (terabytes). + + + + table_name diff --git a/doc/src/sgml/ref/vacuumdb.sgml b/doc/src/sgml/ref/vacuumdb.sgml index 8280cf0fb0..caf97af215 100644 --- a/doc/src/sgml/ref/vacuumdb.sgml +++ b/doc/src/sgml/ref/vacuumdb.sgml @@ -121,6 +121,19 @@ PostgreSQL documentation + + + + + Specifies the + 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 + be reused as part of this strategy. See . + + + + @@ -278,19 +291,6 @@ PostgreSQL documentation - - - - - Specifies the - 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 - be reused as part of this strategy. See . - - - - diff --git a/src/bin/scripts/vacuumdb.c b/src/bin/scripts/vacuumdb.c index 1241644ed5..687af9c1f3 100644 --- a/src/bin/scripts/vacuumdb.c +++ b/src/bin/scripts/vacuumdb.c @@ -1128,6 +1128,7 @@ help(const char *progname) printf(_(" %s [OPTION]... [DBNAME]\n"), progname); printf(_("\nOptions:\n")); printf(_(" -a, --all vacuum all databases\n")); + printf(_(" --buffer-usage-limit=SIZE size of ring buffer used for vacuum\n")); printf(_(" -d, --dbname=DBNAME database to vacuum\n")); printf(_(" --disable-page-skipping disable all page-skipping behavior\n")); printf(_(" -e, --echo show the commands being sent to the server\n")); @@ -1136,7 +1137,6 @@ help(const char *progname) printf(_(" --force-index-cleanup always remove index entries that point to dead tuples\n")); printf(_(" -j, --jobs=NUM use this many concurrent connections to vacuum\n")); printf(_(" --min-mxid-age=MXID_AGE minimum multixact ID age of tables to vacuum\n")); - printf(_(" --buffer-usage-limit=BUFSIZE size of ring buffer used for vacuum\n")); printf(_(" --min-xid-age=XID_AGE minimum transaction ID age of tables to vacuum\n")); printf(_(" --no-index-cleanup don't remove index entries that point to dead tuples\n")); printf(_(" --no-process-main skip the main relation\n"));