Improvements to docs about pg_archive_cleanup and use of archives

Brendan Jurd

diff --git a/doc/src/sgml/high-availability.sgml b/doc/src/sgml/high-availability.sgml
index a4be8276be97b5c2301585dd94dbbf792b4ab2ab..eabd844fa381d24d443867512073170f111711ac 100644 (file)
--- a/doc/src/sgml/high-availability.sgml
+++ b/doc/src/sgml/high-availability.sgml
@@ -680,11 +680,6 @@ protocol to make nodes agree on a serializable transactional order.
      primary_conninfo as well.
    
 
-   
-    You can use archive_cleanup_command to prune the archive of
-    files no longer needed by the standby.
-   
-
    
     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.
    
 
+   
+    If you're using a WAL archive, its size can be minimized using the 
+    linkend="archive-cleanup-command"> parameter to remove files that are no
+    longer required by the standby server.
+    The pg_archivecleanup utility is designed specifically to
+    be used with archive_cleanup_command in typical single-standby
+    configurations, see .
+    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.
+   
+
    
     A simple example of a recovery.conf is:
 
@@ -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'
 
    
 
@@ -712,14 +720,6 @@ trigger_file = '/path/to/trigger_file'
     the primary to allow them to be connected simultaneously.
    
 
-   
-    If you're using a WAL archive, its size can be minimized using
-    the 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.
-   
   
 
   


diff --git a/doc/src/sgml/pgarchivecleanup.sgml b/doc/src/sgml/pgarchivecleanup.sgml

index a01f159fb343bedef4514e8aba693d7423105aab..e5072e6eeba6a998c436e0a10030654f73425ddd 100644 (file)

--- a/doc/src/sgml/pgarchivecleanup.sgml
+++ b/doc/src/sgml/pgarchivecleanup.sgml
@@ -8,10 +8,11 @@
  
 
  
-  pg_archivecleanup is designed to cleanup an archive when used
-  as an archive_cleanup_command when running with
-  standby_mode = on. pg_archivecleanup can
-  also be used as a standalone program to clean WAL file archives.
+  pg_archivecleanup is designed to be used as an
+  archive_cleanup_command to clean up WAL file archives when
+  running as a standby server (see ).
+  pg_archivecleanup can also be used as a standalone program to
+  clean WAL file archives.
  
 
  
@@ -39,20 +40,21 @@
    server to use pg_archivecleanup, put this into its
    recovery.conf configuration file:
 
-archive_cleanup_command = 'pg_archivecleanup archiveDir %r'
+archive_cleanup_command = 'pg_archivecleanup archivelocation %r'
 
-   where archiveDir is the directory from which WAL segment
-   files should be restored.
+   where archivelocation is the directory from which WAL segment
+   files should be removed.
   
   
-   When used within archive_cleanup_command,
-   all WAL files logically preceding the value of the %r
-   will be removed 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
-   archivelocation is a transient staging area for this
-   particular standby server, but not when the
-   archivelocation is intended as a long-term WAL archive area.
+   When used within , all WAL files
+   logically preceding the value of the %r argument will be removed
+   from 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 archivelocation is a
+   transient staging area for this particular standby server, but
+   not when the archivelocation is intended as a
+   long-term WAL archive area, or when multiple standby servers are recovering
+   from the same archive location.
   
   
    The full syntax of pg_archivecleanup's command line is


diff --git a/doc/src/sgml/recovery-config.sgml b/doc/src/sgml/recovery-config.sgml

index d555960b805ee024bd772e037cbae1375eff3b67..220372ba4feaa3ab42c73bfefdd00bbebba70daf 100644 (file)

--- a/doc/src/sgml/recovery-config.sgml
+++ b/doc/src/sgml/recovery-config.sgml
@@ -80,20 +80,30 @@ restore_command = 'copy "C:\\server\\archivedir\\%f" "%p"'  # Windows
       
       
        
-        This parameter specifies a shell command that will be executed at
-        every restartpoint. This parameter is optional. The purpose of the
-        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 %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. %r would
-        typically be used in a warm-standby configuration
-        (see ).
-        Write %% to embed an actual % character
-        in the command.
+        This optional parameter specifies a shell command that will be executed
+        at every restartpoint.  The purpose of
+        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 %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, and so all files earlier than %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 pg_archivecleanup utility provided in
+        contrib (see ) serves as a
+        convenient target for archive_cleanup_command in typical
+        single-standby configurations, for example:
+ archive_cleanup_command = 'pg_archivecleanup /mnt/server/archivedir %r' 
+        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.
+        archive_cleanup_command would typically be used in a
+        warm-standby configuration (see ).
+        Write %% to embed an actual % character in the
+        command.
        
        
         If the command returns a non-zero exit status then a WARNING log

diff --git a/doc/src/sgml/pgarchivecleanup.sgml b/doc/src/sgml/pgarchivecleanup.sgml
index a01f159fb343bedef4514e8aba693d7423105aab..e5072e6eeba6a998c436e0a10030654f73425ddd 100644 (file)
--- a/doc/src/sgml/pgarchivecleanup.sgml
+++ b/doc/src/sgml/pgarchivecleanup.sgml
@@ -8,10 +8,11 @@
  
 
  
-  pg_archivecleanup is designed to cleanup an archive when used
-  as an archive_cleanup_command when running with
-  standby_mode = on. pg_archivecleanup can
-  also be used as a standalone program to clean WAL file archives.
+  pg_archivecleanup is designed to be used as an
+  archive_cleanup_command to clean up WAL file archives when
+  running as a standby server (see ).
+  pg_archivecleanup can also be used as a standalone program to
+  clean WAL file archives.
  
 
  
@@ -39,20 +40,21 @@
    server to use pg_archivecleanup, put this into its
    recovery.conf configuration file:
 
-archive_cleanup_command = 'pg_archivecleanup archiveDir %r'
+archive_cleanup_command = 'pg_archivecleanup archivelocation %r'
 
-   where archiveDir is the directory from which WAL segment
-   files should be restored.
+   where archivelocation is the directory from which WAL segment
+   files should be removed.
   
   
-   When used within archive_cleanup_command,
-   all WAL files logically preceding the value of the %r
-   will be removed 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
-   archivelocation is a transient staging area for this
-   particular standby server, but not when the
-   archivelocation is intended as a long-term WAL archive area.
+   When used within , all WAL files
+   logically preceding the value of the %r argument will be removed
+   from 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 archivelocation is a
+   transient staging area for this particular standby server, but
+   not when the archivelocation is intended as a
+   long-term WAL archive area, or when multiple standby servers are recovering
+   from the same archive location.
   
   
    The full syntax of pg_archivecleanup's command line is

diff --git a/doc/src/sgml/recovery-config.sgml b/doc/src/sgml/recovery-config.sgml
index d555960b805ee024bd772e037cbae1375eff3b67..220372ba4feaa3ab42c73bfefdd00bbebba70daf 100644 (file)
--- a/doc/src/sgml/recovery-config.sgml
+++ b/doc/src/sgml/recovery-config.sgml
@@ -80,20 +80,30 @@ restore_command = 'copy "C:\\server\\archivedir\\%f" "%p"'  # Windows
       
       
        
-        This parameter specifies a shell command that will be executed at
-        every restartpoint. This parameter is optional. The purpose of the
-        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 %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. %r would
-        typically be used in a warm-standby configuration
-        (see ).
-        Write %% to embed an actual % character
-        in the command.
+        This optional parameter specifies a shell command that will be executed
+        at every restartpoint.  The purpose of
+        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 %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, and so all files earlier than %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 pg_archivecleanup utility provided in
+        contrib (see ) serves as a
+        convenient target for archive_cleanup_command in typical
+        single-standby configurations, for example:
+ archive_cleanup_command = 'pg_archivecleanup /mnt/server/archivedir %r' 
+        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.
+        archive_cleanup_command would typically be used in a
+        warm-standby configuration (see ).
+        Write %% to embed an actual % character in the
+        command.
        
        
         If the command returns a non-zero exit status then a WARNING log