Improvements to docs about pg_archive_cleanup and use of archives

Brendan Jurd

doc/src/sgml/high-availability.sgml

@@ -680,11 +680,6 @@ protocol to make nodes agree on a serializable transactional order.
      <varname>primary_conninfo</> as well.
    </para>
 
-   <para>
-    You can use <varname>archive_cleanup_command</> to prune the archive of
-    files no longer needed by the standby.
-   </para>
-
    <para>
     If you're setting up the standby server for high availability purposes,
     set up WAL archiving, connections and authentication like the primary
@@ -696,6 +691,18 @@ protocol to make nodes agree on a serializable transactional order.
     is not required.
    </para>
 
+   <para>
+    If you're using a WAL archive, its size can be minimized using the <xref
+    linkend="archive-cleanup-command"> parameter to remove files that are no
+    longer required by the standby server.
+    The <application>pg_archivecleanup</> utility is designed specifically to
+    be used with <varname>archive_cleanup_command</> in typical single-standby
+    configurations, see <xref linkend="pgarchivecleanup">.
+    Note however, that if you're using the archive for backup purposes, you
+    need to retain files needed to recover from at least the latest base
+    backup, even if they're no longer needed by the standby.
+   </para>
+
    <para>
     A simple example of a <filename>recovery.conf</> is:
 <programlisting>
@@ -703,6 +710,7 @@ standby_mode = 'on'
 primary_conninfo = 'host=192.168.1.50 port=5432 user=foo password=foopass'
 restore_command = 'cp /path/to/archive/%f %p'
 trigger_file = '/path/to/trigger_file'
+archive_cleanup_command = 'pg_archivecleanup /path/to/archive %r'
 </programlisting>
    </para>
 
@@ -712,14 +720,6 @@ trigger_file = '/path/to/trigger_file'
     the primary to allow them to be connected simultaneously.
    </para>
 
-   <para>
-    If you're using a WAL archive, its size can be minimized using
-    the <varname>archive_cleanup_command</> option to remove files that are
-    no longer required by the standby server. Note however, that if you're
-    using the archive for backup purposes, you need to retain files needed
-    to recover from at least the latest base backup, even if they're no
-    longer needed by the standby.
-   </para>
   </sect2>
 
   <sect2 id="streaming-replication">

doc/src/sgml/pgarchivecleanup.sgml

@@ -8,10 +8,11 @@
  </indexterm>
 
  <para>
-  <application>pg_archivecleanup</> is designed to cleanup an archive when used
-  as an <literal>archive_cleanup_command</literal> when running with
-  <literal>standby_mode = on</literal>. <application>pg_archivecleanup</> can
-  also be used as a standalone program to clean WAL file archives.
+  <application>pg_archivecleanup</> is designed to be used as an
+  <literal>archive_cleanup_command</literal> to clean up WAL file archives when
+  running as a standby server (see <xref linkend="warm-standby">).
+  <application>pg_archivecleanup</> can also be used as a standalone program to
+  clean WAL file archives.
  </para>
 
  <para>
@@ -39,20 +40,21 @@
    server to use <application>pg_archivecleanup</>, put this into its
    <filename>recovery.conf</filename> configuration file:
 <programlisting>
-archive_cleanup_command = 'pg_archivecleanup <replaceable>archiveDir</> %r'
+archive_cleanup_command = 'pg_archivecleanup <replaceable>archivelocation</> %r'
 </programlisting>
-   where <replaceable>archiveDir</> is the directory from which WAL segment
-   files should be restored.
+   where <replaceable>archivelocation</> is the directory from which WAL segment
+   files should be removed.
   </para>
   <para>
-   When used within <literal>archive_cleanup_command</literal>,
-   all WAL files logically preceding the value of the <literal>%r</>
-   will be removed <replaceable>archivelocation</>. This minimizes
-   the number of files that need to be retained, while preserving
-   crash-restart capability.  Use of this parameter is appropriate if the
-   <replaceable>archivelocation</> is a transient staging area for this
-   particular standby server, but <emphasis>not</> when the
-   <replaceable>archivelocation</> is intended as a long-term WAL archive area.
+   When used within <xref linkend="archive-cleanup-command">, all WAL files
+   logically preceding the value of the <literal>%r</> argument will be removed
+   from <replaceable>archivelocation</>. This minimizes the number of files
+   that need to be retained, while preserving crash-restart capability.  Use of
+   this parameter is appropriate if the <replaceable>archivelocation</> is a
+   transient staging area for this particular standby server, but
+   <emphasis>not</> when the <replaceable>archivelocation</> is intended as a
+   long-term WAL archive area, or when multiple standby servers are recovering
+   from the same archive location.
   </para>
   <para>
    The full syntax of <application>pg_archivecleanup</>'s command line is

doc/src/sgml/recovery-config.sgml

@@ -80,20 +80,30 @@ restore_command = 'copy "C:\\server\\archivedir\\%f" "%p"'  # Windows
       </indexterm>
       <listitem>
        <para>
-        This parameter specifies a shell command that will be executed at
-        every restartpoint. This parameter is optional. The purpose of the
-        <varname>archive_cleanup_command</> is to provide a mechanism for cleaning
-        up old archived WAL files that are no longer needed by the standby
-        server.
-        Any <literal>%r</> is replaced by the name of the file
-        containing the last valid restart point. That is the earliest file that
-        must be kept to allow a restore to be restartable, so this information
-        can be used to truncate the archive to just the minimum required to
-        support restart from the current restore. <literal>%r</> would
-        typically be used in a warm-standby configuration
-        (see <xref linkend="warm-standby">).
-        Write <literal>%%</> to embed an actual <literal>%</> character
-        in the command.
+        This optional parameter specifies a shell command that will be executed
+        at every restartpoint.  The purpose of
+        <varname>archive_cleanup_command</> is to provide a mechanism for
+        cleaning up old archived WAL files that are no longer needed by the
+        standby server.
+        Any <literal>%r</> is replaced by the name of the file containing the
+        last valid restart point.
+        That is the earliest file that must be <emphasis>kept</> to allow a
+        restore to be restartable, and so all files earlier than <literal>%r</>
+        may be safely removed.
+        This information can be used to truncate the archive to just the
+        minimum required to support restart from the current restore.
+        The <application>pg_archivecleanup</> utility provided in
+        <literal>contrib</> (see <xref linkend="pgarchivecleanup">) serves as a
+        convenient target for <varname>archive_cleanup_command</> in typical
+        single-standby configurations, for example:
+<programlisting> archive_cleanup_command = 'pg_archivecleanup /mnt/server/archivedir %r' </programlisting>
+        Note however that if multiple standby servers are restoring from the
+        same archive directory, you will need to ensure that you do not delete
+        WAL files until they are no longer needed by any of the servers.
+        <varname>archive_cleanup_command</> would typically be used in a
+        warm-standby configuration (see <xref linkend="warm-standby">).
+        Write <literal>%%</> to embed an actual <literal>%</> character in the
+        command.
        </para>
        <para>
         If the command returns a non-zero exit status then a WARNING log