From 7085891784784fda7314c0510da901fc8402380a Mon Sep 17 00:00:00 2001 From: Simon Riggs Date: Thu, 14 Oct 2010 19:30:15 +0100 Subject: [PATCH] Improvements to docs about pg_archive_cleanup and use of archives Brendan Jurd --- doc/src/sgml/high-availability.sgml | 26 ++++++++++---------- doc/src/sgml/pgarchivecleanup.sgml | 32 ++++++++++++------------ doc/src/sgml/recovery-config.sgml | 38 ++++++++++++++++++----------- 3 files changed, 54 insertions(+), 42 deletions(-) diff --git a/doc/src/sgml/high-availability.sgml b/doc/src/sgml/high-availability.sgml index 9b4fa3a6d2..cc11a1e0ef 100644 --- 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 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 b07840cdc1..e324b1483a 100644 --- 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 baddf59de6..bd9dfd177a 100644 --- 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 -- 2.40.0