From b1bba6df919d98545ee4d49f6bb8b4892ed55b27 Mon Sep 17 00:00:00 2001
From: Peter Geoghegan <pg@bowt.ie>
Date: Sat, 22 Apr 2023 12:11:10 -0700
Subject: [PATCH v3 7/9] Make maintenance.sgml more autovacuum-orientated.

Now that it's no longer in its own sect2, shorten the "Vacuuming basics"
content, and make it more autovacuum-orientated.  This gives much less
prominence to VACUUM FULL, which has little place in a section about
autovacuum.  We no longer define avoiding the need to run VACUUM FULL as
the purpose of vacuuming.

A later commit that overhauls "Recovering Disk Space" will add back a
passing mention of things like VACUUM FULL and TRUNCATE, but only as
something that might be relevant in extreme cases.  (Use of these
commands is hopefully neither "Routine" nor "Basic" to most users).

Also add some introductory information about the audience and goals of
the "Routine Vacuuming" section of the docs.
---
 doc/src/sgml/maintenance.sgml | 122 +++++++++++++++++++++-------------
 1 file changed, 76 insertions(+), 46 deletions(-)

diff --git a/doc/src/sgml/maintenance.sgml b/doc/src/sgml/maintenance.sgml
index a05e880fc..36f481aba 100644
--- a/doc/src/sgml/maintenance.sgml
+++ b/doc/src/sgml/maintenance.sgml
@@ -32,11 +32,12 @@
  </para>
 
  <para>
-  The other main category of maintenance task is periodic <quote>vacuuming</quote>
-  of the database.  This activity is discussed in
-  <xref linkend="routine-vacuuming"/>.  Closely related to this is updating
-  the statistics that will be used by the query planner, as discussed in
-  <xref linkend="vacuum-for-statistics"/>.
+  The other main category of maintenance task is periodic
+  <quote><link linkend="routine-vacuuming">vacuuming</link></quote> of
+  the database by autovacuum.  Configuring autovacuum scheduling is
+  discussed in <xref linkend="autovacuum"/>.  Autovacuum also updates
+  the statistics that will be used by the query planner, as discussed
+  in <xref linkend="vacuum-for-statistics"/>.
  </para>
 
  <para>
@@ -244,7 +245,7 @@ analyze threshold = analyze base threshold + analyze scale factor * number of tu
  </sect1>
 
  <sect1 id="routine-vacuuming">
-  <title>Routine Vacuuming</title>
+  <title>Autovacuum Maintenance Tasks</title>
 
   <indexterm zone="routine-vacuuming">
    <primary>vacuum</primary>
@@ -252,24 +253,18 @@ analyze threshold = analyze base threshold + analyze scale factor * number of tu
 
   <para>
    <productname>PostgreSQL</productname> databases require periodic
-   maintenance known as <firstterm>vacuuming</firstterm>.  For many installations, it
-   is sufficient to let vacuuming be performed by the <firstterm>autovacuum
-   daemon</firstterm>, which is described in <xref linkend="autovacuum"/>.  You might
-   need to adjust the autovacuuming parameters described there to obtain best
-   results for your situation.  Some database administrators will want to
-   supplement or replace the daemon's activities with manually-managed
-   <command>VACUUM</command> commands, which typically are executed according to a
-   schedule by <application>cron</application> or <application>Task
-   Scheduler</application> scripts.  To set up manually-managed vacuuming properly,
-   it is essential to understand the issues discussed in the next few
-   subsections.  Administrators who rely on autovacuuming may still wish
-   to skim this material to help them understand and adjust autovacuuming.
+   maintenance known as <firstterm>vacuuming</firstterm>, and require
+   periodic updates to the statistics used by the
+   <productname>PostgreSQL</productname> query planner.  The <link
+    linkend="sql-vacuum"><command>VACUUM</command></link> and <link
+    linkend="sql-analyze"><command>ANALYZE</command></link> commands
+   perform these maintenance tasks.  The <firstterm>autovacuum
+    daemon</firstterm> automatically schedules execution of
+   maintenance, based on the requirements of the workload.
   </para>
-
   <para>
-   <productname>PostgreSQL</productname>'s
-   <link linkend="sql-vacuum"><command>VACUUM</command></link> command has to
-   process each table on a regular basis for several reasons:
+   The autovacuum daemon has to process each table regularly for
+   several reasons:
 
    <orderedlist>
     <listitem>
@@ -295,34 +290,69 @@ analyze threshold = analyze base threshold + analyze scale factor * number of tu
     </listitem>
    </orderedlist>
 
-   Each of these reasons dictates performing <command>VACUUM</command> operations
-   of varying frequency and scope, as explained in the following subsections.
+   Maintenance work within the scope of items 1, 2, 3, and 4 is
+   performed by the <command>VACUUM</command> command internally.  The
+   <command>ANALYZE</command> command handles maintenance work within
+   the scope of item 5 (maintenance of planner statistics) internally.
   </para>
-
   <para>
-   There are two variants of <command>VACUUM</command>: standard <command>VACUUM</command>
-   and <command>VACUUM FULL</command>.  <command>VACUUM FULL</command> can reclaim more
-   disk space but runs much more slowly.  Also,
-   the standard form of <command>VACUUM</command> can run in parallel with production
-   database operations.  (Commands such as <command>SELECT</command>,
-   <command>INSERT</command>, <command>UPDATE</command>, and
-   <command>DELETE</command> will continue to function normally, though you
-   will not be able to modify the definition of a table with commands such as
-   <command>ALTER TABLE</command> while it is being vacuumed.)
-   <command>VACUUM FULL</command> requires an
-   <literal>ACCESS EXCLUSIVE</literal> lock on the table it is
-   working on, and therefore cannot be done in parallel with other use
-   of the table.  Generally, therefore,
-   administrators should strive to use standard <command>VACUUM</command> and
-   avoid <command>VACUUM FULL</command>.
+   Generally speaking, database administrators that are new to tuning
+   autovacuum should start by considering adjusting autovacuum's
+   scheduling.  Autovacuum scheduling is controlled via threshold
+   settings.  These settings determine when autovacuum should launch a
+   worker to run <command>VACUUM</command> and/or
+   <command>ANALYZE</command>; see the previous section, <xref
+    linkend="autovacuum"/>.  This section provides additional
+   information about the design and goals of autovacuum,
+   <command>VACUUM</command>, and <command>ANALYZE</command>.  The
+   intended audience is database administrators that wish to perform
+   more advanced tuning of autovacuum, with any of the following goals
+   in mind:
   </para>
-
+  <itemizedlist>
+   <listitem>
+    <para>
+     Tuning <command>VACUUM</command> to improve query response times.
+    </para>
+   </listitem>
+   <listitem>
+    <para>
+     Making sure that <command>VACUUM</command>'s management of the
+     Transaction ID address space is operating normally.
+    </para>
+   </listitem>
+   <listitem>
+    <para>
+     Tuning <command>VACUUM</command> for performance stability.
+    </para>
+   </listitem>
+  </itemizedlist>
   <para>
-   <command>VACUUM</command> creates a substantial amount of I/O
-   traffic, which can cause poor performance for other active sessions.
-   There are configuration parameters that can be adjusted to reduce the
-   performance impact of background vacuuming &mdash; see
-   <xref linkend="runtime-config-resource-vacuum-cost"/>.
+   With larger installations, tuning autovacuum usually won't be a
+   once-off task; it is best to approach tuning as an iterative,
+   applied process.  FIXME Expand this to describe the intended
+   audience on goals in a fully worked out way.
+  </para>
+  <para>
+   Autovacuum creates a substantial amount of I/O traffic, which can
+   cause poor performance for other active sessions.  There are
+   configuration parameters that you can adjust to reduce the
+   performance impact of background vacuuming.  See the
+   autovacuum-specific cost delay settings described in <xref
+    linkend="runtime-config-autovacuum"/>, and additional cost delay
+   settings described in <xref
+    linkend="runtime-config-resource-vacuum-cost"/>.
+  </para>
+  <para>
+   Some database administrators will want to supplement the daemon's
+   activities with manually-managed <command>VACUUM</command>
+   commands.  Scripting tools like <application>cron</application> and
+   <application>Task Manager</application> can be of help with this.
+   It can be useful to perform off-hours <command>VACUUM</command>
+   commands during periods where reduced load is expected.  Almost all
+   of the contents of this section apply equally to manually-issued
+   <command>VACUUM</command> and <command>ANALYZE</command>
+   operations.
   </para>
 
   <sect2 id="vacuum-for-space-recovery">
-- 
2.40.1

