[patch] [doc] Further note required activity aspect of automatic checkpoint and archving

[David G. Johnston]

Hackers,

Over in general [1] Robert Inder griped about the not-so-recent change to
our automatic checkpointing, and thus archiving, behavior where
non-activity results in nothing happening.  In looking over the
documentation I felt a few changes could be made to increase the chance
that a reader learns this key dynamic.  Attached is a patch with those
changes.  Copied inline for ease of review.

commit 8af7f653907688252d8663a80e945f6f5782b0de
Author: David G. Johnston <david.g.johns...@gmail.com>
Date:   Mon Oct 12 21:32:32 2020 +0000

    Further note required activity aspect of automatic checkpoint and
archiving

    A few spots in the documentation could use a reminder that checkpoints
    and archiving requires that actual WAL records be written in order to
happen
    automatically.

diff --git a/doc/src/sgml/backup.sgml b/doc/src/sgml/backup.sgml
index 42a8ed328d..c312fc9387 100644
--- a/doc/src/sgml/backup.sgml
+++ b/doc/src/sgml/backup.sgml
@@ -722,6 +722,8 @@ test ! -f
/mnt/server/archivedir/00000001000000A900000065 &amp;&amp; cp pg_wal/0
     short <varname>archive_timeout</varname> &mdash; it will bloat your
archive
     storage.  <varname>archive_timeout</varname> settings of a minute or
so are
     usually reasonable.
+    This is mitigated by the fact that empty WAL segments will not be
archived
+    even if the archive_timeout period has elapsed.
    </para>

    <para>
diff --git a/doc/src/sgml/config.sgml b/doc/src/sgml/config.sgml
index ee914740cc..306f78765c 100644
--- a/doc/src/sgml/config.sgml
+++ b/doc/src/sgml/config.sgml
@@ -3131,6 +3131,8 @@ include_dir 'conf.d'
       <listitem>
        <para>
         Maximum time between automatic WAL checkpoints.
+        The automatic checkpoint will do nothing if no new WAL has been
+        written since the last recorded checkpoint.
         If this value is specified without units, it is taken as seconds.
         The valid range is between 30 seconds and one day.
         The default is five minutes (<literal>5min</literal>).
@@ -3337,18 +3339,17 @@ include_dir 'conf.d'
       </term>
       <listitem>
        <para>
+        Force the completion of the current, non-empty, WAL segment when
+        this amount of time (if non-zero) has elapsed since the last
+        segment file switch.
         The <xref linkend="guc-archive-command"/> is only invoked for
         completed WAL segments. Hence, if your server generates little WAL
         traffic (or has slack periods where it does so), there could be a
         long delay between the completion of a transaction and its safe
         recording in archive storage.  To limit how old unarchived
         data can be, you can set <varname>archive_timeout</varname> to
force the
-        server to switch to a new WAL segment file periodically.  When this
-        parameter is greater than zero, the server will switch to a new
-        segment file whenever this amount of time has elapsed since the
last
-        segment file switch, and there has been any database activity,
-        including a single checkpoint (checkpoints are skipped if there is
-        no database activity).  Note that archived files that are closed
+        server to switch to a new WAL segment file periodically.
+        Note that archived files that are closed
         early due to a forced switch are still the same length as
completely
         full files.  Therefore, it is unwise to use a very short
         <varname>archive_timeout</varname> &mdash; it will bloat your
archive

David J.

[1]
https://www.postgresql.org/message-id/flat/CAKqjJm83gnw2u0ugpkgc4bq58L%3DcLwbvmh69TwKKo83Y1CnANw%40mail.gmail.com

v1-doc-automatic-checkpoint-and-archive-skips.patch
Description: Binary data