diff options
| -rw-r--r-- | doc/src/sgml/high-availability.sgml | 26 | ||||
| -rw-r--r-- | doc/src/sgml/pgarchivecleanup.sgml | 32 | ||||
| -rw-r--r-- | 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 a4be8276be9..eabd844fa38 100644 --- a/doc/src/sgml/high-availability.sgml +++ b/doc/src/sgml/high-availability.sgml @@ -681,11 +681,6 @@ protocol to make nodes agree on a serializable transactional order. </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 server, because the standby server will work as a primary server after @@ -697,12 +692,25 @@ protocol to make nodes agree on a serializable transactional order. </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> 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"> diff --git a/doc/src/sgml/pgarchivecleanup.sgml b/doc/src/sgml/pgarchivecleanup.sgml index a01f159fb34..e5072e6eeba 100644 --- a/doc/src/sgml/pgarchivecleanup.sgml +++ b/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 diff --git a/doc/src/sgml/recovery-config.sgml b/doc/src/sgml/recovery-config.sgml index d555960b805..220372ba4fe 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 </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 |