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

diff --git a/doc/src/sgml/ref/analyze.sgml b/doc/src/sgml/ref/analyze.sgml
index 94e30f1ce742d2550e494667e6e3a5505dba0c17..20c6f9939fd264a7bd32e8ef207cd75531cc26cf 100644 (file)
--- a/doc/src/sgml/ref/analyze.sgml
+++ b/doc/src/sgml/ref/analyze.sgml
@@ -28,7 +28,7 @@ ANALYZE [ VERBOSE ] [ <replaceable class="parameter">table_and_columns</replacea
 
     VERBOSE [ <replaceable class="parameter">boolean</replaceable> ]
     SKIP_LOCKED [ <replaceable class="parameter">boolean</replaceable> ]
-    BUFFER_USAGE_LIMIT [ <replaceable class="parameter">string</replaceable> ]
+    BUFFER_USAGE_LIMIT [ <replaceable class="parameter">size</replaceable> ]
 
 <phrase>and <replaceable class="parameter">table_and_columns</replaceable> is:</phrase>
 
@@ -110,7 +110,8 @@ ANALYZE [ VERBOSE ] [ <replaceable class="parameter">table_and_columns</replacea
       <xref linkend="guc-vacuum-buffer-usage-limit"/>.  Higher settings can
       allow <command>ANALYZE</command> 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 <literal>128 kB</literal> and the
+      maximum value is <literal>16 GB</literal>.
      </para>
     </listitem>
    </varlistentry>
@@ -129,6 +130,19 @@ ANALYZE [ VERBOSE ] [ <replaceable class="parameter">table_and_columns</replacea
     </listitem>
    </varlistentry>
 
+   <varlistentry>
+    <term><replaceable class="parameter">size</replaceable></term>
+    <listitem>
+     <para>
+      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: <literal>kB</literal> (kilobytes),
+      <literal>MB</literal> (megabytes), <literal>GB</literal> (gigabytes), or
+      <literal>TB</literal> (terabytes).
+     </para>
+    </listitem>
+   </varlistentry>
+
    <varlistentry>
     <term><replaceable class="parameter">table_name</replaceable></term>
     <listitem>

diff --git a/doc/src/sgml/ref/vacuum.sgml b/doc/src/sgml/ref/vacuum.sgml
index dd0fbb8cb7529634b7dd2de9f264128aa76315a3..57bc4c23ec0b7a50f4b5cc8cfaf27000b1a9e037 100644 (file)
--- a/doc/src/sgml/ref/vacuum.sgml
+++ b/doc/src/sgml/ref/vacuum.sgml
@@ -39,7 +39,7 @@ VACUUM [ FULL ] [ FREEZE ] [ VERBOSE ] [ ANALYZE ] [ <replaceable class="paramet
     PARALLEL <replaceable class="parameter">integer</replaceable>
     SKIP_DATABASE_STATS [ <replaceable class="parameter">boolean</replaceable> ]
     ONLY_DATABASE_STATS [ <replaceable class="parameter">boolean</replaceable> ]
-    BUFFER_USAGE_LIMIT [ <replaceable class="parameter">string</replaceable> ]
+    BUFFER_USAGE_LIMIT [ <replaceable class="parameter">size</replaceable> ]
 
 <phrase>and <replaceable class="parameter">table_and_columns</replaceable> is:</phrase>
 
@@ -364,7 +364,8 @@ VACUUM [ FULL ] [ FREEZE ] [ VERBOSE ] [ ANALYZE ] [ <replaceable class="paramet
       <xref linkend="guc-vacuum-buffer-usage-limit"/>.  Higher settings can
       allow <command>VACUUM</command> 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 <literal>128 kB</literal> and the
+      maximum value is <literal>16 GB</literal>.
      </para>
     </listitem>
    </varlistentry>
@@ -392,6 +393,19 @@ VACUUM [ FULL ] [ FREEZE ] [ VERBOSE ] [ ANALYZE ] [ <replaceable class="paramet
     </listitem>
    </varlistentry>
 
+   <varlistentry>
+    <term><replaceable class="parameter">size</replaceable></term>
+    <listitem>
+     <para>
+      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: <literal>kB</literal> (kilobytes),
+      <literal>MB</literal> (megabytes), <literal>GB</literal> (gigabytes), or
+      <literal>TB</literal> (terabytes).
+     </para>
+    </listitem>
+   </varlistentry>
+
    <varlistentry>
     <term><replaceable class="parameter">table_name</replaceable></term>
     <listitem>

diff --git a/doc/src/sgml/ref/vacuumdb.sgml b/doc/src/sgml/ref/vacuumdb.sgml
index 8280cf0fb07d11f40bc77d85d0dcfd74820f18cd..caf97af215d2838b52b26b2e4908e45bdfcd60e1 100644 (file)
--- a/doc/src/sgml/ref/vacuumdb.sgml
+++ b/doc/src/sgml/ref/vacuumdb.sgml
@@ -121,6 +121,19 @@ PostgreSQL documentation
       </listitem>
      </varlistentry>
 
+     <varlistentry>
+      <term><option>--buffer-usage-limit <replaceable class="parameter">size</replaceable></option></term>
+      <listitem>
+       <para>
+        Specifies the
+        <glossterm linkend="glossary-buffer-access-strategy">Buffer Access Strategy</glossterm>
+        ring buffer size for a given invocation of <application>vacuumdb</application>.
+        This size is used to calculate the number of shared buffers which will
+        be reused as part of this strategy.  See <xref linkend="sql-vacuum"/>.
+       </para>
+      </listitem>
+     </varlistentry>
+
      <varlistentry>
       <term><option><optional>-d</optional> <replaceable class="parameter">dbname</replaceable></option></term>
       <term><option><optional>--dbname=</optional><replaceable class="parameter">dbname</replaceable></option></term>
@@ -278,19 +291,6 @@ PostgreSQL documentation
       </listitem>
      </varlistentry>
 
-     <varlistentry>
-      <term><option>--buffer-usage-limit <replaceable class="parameter">buffer_usage_limit</replaceable></option></term>
-      <listitem>
-       <para>
-        Specifies the
-        <glossterm linkend="glossary-buffer-access-strategy">Buffer Access Strategy</glossterm>
-        ring buffer size for a given invocation of <application>vacuumdb</application>.
-        This size is used to calculate the number of shared buffers which will
-        be reused as part of this strategy.  See <xref linkend="sql-vacuum"/>.
-       </para>
-      </listitem>
-     </varlistentry>
-
      <varlistentry>
       <term><option>-n <replaceable class="parameter">schema</replaceable></option></term>
       <term><option>--schema=<replaceable class="parameter">schema</replaceable></option></term>

diff --git a/src/bin/scripts/vacuumdb.c b/src/bin/scripts/vacuumdb.c
index 1241644ed5e445f322ced63c2739a11c78d12d2b..687af9c1f30b929f04c978d53fdac1b5b24fc77c 100644 (file)
--- 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"));