Adding upstream version 13.4.upstream/13.4upstream

Signed-off-by: Daniel Baumann <daniel.baumann@progress-linux.org>

1 files changed, 394 insertions, 0 deletions

diff --git a/doc/src/sgml/pgstandby.sgml b/doc/src/sgml/pgstandby.sgml
new file mode 100644
index 0000000..d8aded4
--- /dev/null
+++ b/doc/src/sgml/pgstandby.sgml
@@ -0,0 +1,394 @@
+<!-- doc/src/sgml/pgstandby.sgml -->
+
+<refentry id="pgstandby">
+ <indexterm zone="pgstandby">
+  <primary>pg_standby</primary>
+ </indexterm>
+
+ <refmeta>
+  <refentrytitle><application>pg_standby</application></refentrytitle>
+  <manvolnum>1</manvolnum>
+  <refmiscinfo>Application</refmiscinfo>
+ </refmeta>
+
+ <refnamediv>
+  <refname>pg_standby</refname>
+  <refpurpose>supports the creation of a <productname>PostgreSQL</productname> warm standby server</refpurpose>
+ </refnamediv>
+
+ <refsynopsisdiv>
+  <cmdsynopsis>
+   <command>pg_standby</command>
+   <arg rep="repeat"><replaceable>option</replaceable></arg>
+   <arg choice="plain"><replaceable>archivelocation</replaceable></arg>
+   <arg choice="plain"><replaceable>nextwalfile</replaceable></arg>
+   <arg choice="plain"><replaceable>walfilepath</replaceable></arg>
+   <arg choice="opt"><replaceable>restartwalfile</replaceable></arg>
+  </cmdsynopsis>
+ </refsynopsisdiv>
+
+ <refsect1>
+  <title>Description</title>
+
+ <para>
+  <application>pg_standby</application> supports creation of a <quote>warm standby</quote>
+  database server.  It is designed to be a production-ready program, as well
+  as a customizable template should you require specific modifications.
+ </para>
+
+ <para>
+  <application>pg_standby</application> is designed to be a waiting
+  <varname>restore_command</varname>, which is needed to turn a standard
+  archive recovery into a warm standby operation.  Other
+  configuration is required as well, all of which is described in the main
+  server manual (see <xref linkend="warm-standby"/>).
+ </para>
+
+  <para>
+   To configure a standby
+   server to use <application>pg_standby</application>, put this into its
+   <filename>postgresql.conf</filename> configuration file:
+<programlisting>
+restore_command = 'pg_standby <replaceable>archiveDir</replaceable> %f %p %r'
+</programlisting>
+   where <replaceable>archiveDir</replaceable> is the directory from which WAL segment
+   files should be restored.
+  </para>
+  <para>
+   If <replaceable>restartwalfile</replaceable> is specified, normally by using the
+   <literal>%r</literal> macro, then all WAL files logically preceding this
+   file will be removed from <replaceable>archivelocation</replaceable>. 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</replaceable> is a transient staging area for this
+   particular standby server, but <emphasis>not</emphasis> when the
+   <replaceable>archivelocation</replaceable> is intended as a long-term WAL archive area.
+  </para>
+  <para>
+   <application>pg_standby</application> assumes that
+   <replaceable>archivelocation</replaceable> is a directory readable by the
+   server-owning user.  If <replaceable>restartwalfile</replaceable> (or <literal>-k</literal>)
+   is specified,
+   the <replaceable>archivelocation</replaceable> directory must be writable too.
+  </para>
+  <para>
+   There are two ways to fail over to a <quote>warm standby</quote> database server
+   when the master server fails:
+
+   <variablelist>
+    <varlistentry>
+     <term>Smart Failover</term>
+     <listitem>
+      <para>
+       In smart failover, the server is brought up after applying all WAL
+       files available in the archive. This results in zero data loss, even if
+       the standby server has fallen behind, but if there is a lot of
+       unapplied WAL it can be a long time before the standby server becomes
+       ready. To trigger a smart failover, create a trigger file containing
+       the word <literal>smart</literal>, or just create it and leave it empty.
+      </para>
+     </listitem>
+    </varlistentry>
+    <varlistentry>
+     <term>Fast Failover</term>
+     <listitem>
+      <para>
+       In fast failover, the server is brought up immediately. Any WAL files
+       in the archive that have not yet been applied will be ignored, and
+       all transactions in those files are lost. To trigger a fast failover,
+       create a trigger file and write the word <literal>fast</literal> into it.
+       <application>pg_standby</application> can also be configured to execute a fast
+       failover automatically if no new WAL file appears within a defined
+       interval.
+      </para>
+     </listitem>
+    </varlistentry>
+   </variablelist>
+  </para>
+
+ </refsect1>
+
+ <refsect1>
+  <title>Options</title>
+
+   <para>
+    <application>pg_standby</application> accepts the following command-line arguments:
+
+    <variablelist>
+
+     <varlistentry>
+      <term><option>-c</option></term>
+      <listitem>
+       <para>
+        Use <literal>cp</literal> or <literal>copy</literal> command to restore WAL files
+        from archive.  This is the only supported behavior so this option is useless.
+       </para>
+      </listitem>
+     </varlistentry>
+
+     <varlistentry>
+      <term><option>-d</option></term>
+      <listitem>
+       <para>
+        Print lots of debug logging output on <filename>stderr</filename>.
+       </para>
+      </listitem>
+     </varlistentry>
+
+     <varlistentry>
+      <term><option>-k</option></term>
+      <listitem>
+       <para>
+        Remove files from <replaceable>archivelocation</replaceable> so that
+        no more than this many WAL files before the current one are kept in the
+        archive.  Zero (the default) means not to remove any files from
+        <replaceable>archivelocation</replaceable>.
+        This parameter will be silently ignored if
+        <replaceable>restartwalfile</replaceable> is specified, since that
+        specification method is more accurate in determining the correct
+        archive cut-off point.
+        Use of this parameter is <emphasis>deprecated</emphasis> as of
+        <productname>PostgreSQL</productname> 8.3; it is safer and more efficient to
+        specify a <replaceable>restartwalfile</replaceable> parameter.  A too
+        small setting could result in removal of files that are still needed
+        for a restart of the standby server, while a too large setting wastes
+        archive space.
+       </para>
+      </listitem>
+     </varlistentry>
+
+     <varlistentry>
+      <term><option>-r</option> <replaceable>maxretries</replaceable></term>
+      <listitem>
+       <para>
+        Set the maximum number of times to retry the copy command if
+        it fails (default 3). After each failure, we wait for
+        <replaceable>sleeptime</replaceable> * <replaceable>num_retries</replaceable>
+        so that the wait time increases progressively.  So by default,
+        we will wait 5 secs, 10 secs, then 15 secs before reporting
+        the failure back to the standby server. This will be
+        interpreted as end of recovery and the standby will come
+        up fully as a result.
+       </para>
+      </listitem>
+     </varlistentry>
+
+     <varlistentry>
+      <term><option>-s</option> <replaceable>sleeptime</replaceable></term>
+      <listitem>
+       <para>
+        Set the number of seconds (up to 60, default 5) to sleep between
+        tests to see if the WAL file to be restored is available in
+        the archive yet.  The default setting is not necessarily
+        recommended; consult <xref linkend="warm-standby"/> for discussion.
+       </para>
+      </listitem>
+     </varlistentry>
+
+     <varlistentry>
+      <term><option>-t</option> <replaceable>triggerfile</replaceable></term>
+      <listitem>
+       <para>
+        Specify a trigger file whose presence should cause failover.
+        It is recommended that you use a structured file name to
+        avoid confusion as to which server is being triggered
+        when multiple servers exist on the same system; for example
+        <filename>/tmp/pgsql.trigger.5432</filename>.
+       </para>
+      </listitem>
+     </varlistentry>
+
+     <varlistentry>
+      <term><option>-V</option></term>
+      <term><option>--version</option></term>
+      <listitem>
+       <para>
+        Print the <application>pg_standby</application> version and exit.
+       </para>
+      </listitem>
+     </varlistentry>
+
+     <varlistentry>
+      <term><option>-w</option> <replaceable>maxwaittime</replaceable></term>
+      <listitem>
+       <para>
+        Set the maximum number of seconds to wait for the next WAL file,
+        after which a fast failover will be performed.
+        A setting of zero (the default) means wait forever.
+        The default setting is not necessarily recommended;
+        consult <xref linkend="warm-standby"/> for discussion.
+       </para>
+      </listitem>
+     </varlistentry>
+
+     <varlistentry>
+      <term><option>-?</option></term>
+      <term><option>--help</option></term>
+      <listitem>
+       <para>
+        Show help about <application>pg_standby</application> command line
+        arguments, and exit.
+       </para>
+      </listitem>
+     </varlistentry>
+    </variablelist>
+   </para>
+
+ </refsect1>
+
+ <refsect1>
+  <title>Notes</title>
+
+  <para>
+   <application>pg_standby</application> is designed to work with
+   <productname>PostgreSQL</productname> 8.2 and later.
+  </para>
+  <para>
+   <productname>PostgreSQL</productname> 8.3 provides the <literal>%r</literal> macro,
+   which is designed to let <application>pg_standby</application> know the
+   last file it needs to keep.  With <productname>PostgreSQL</productname> 8.2, the
+   <literal>-k</literal> option must be used if archive cleanup is
+   required.  This option remains available in 8.3, but its use is deprecated.
+  </para>
+  <para>
+   <productname>PostgreSQL</productname> 8.4 provides the
+   <varname>recovery_end_command</varname> option.  Without this option
+   a leftover trigger file can be hazardous.
+  </para>
+
+  <para>
+   <application>pg_standby</application> is written in C and has an
+   easy-to-modify source code, with specifically designated sections to modify
+   for your own needs
+  </para>
+ </refsect1>
+
+ <refsect1>
+  <title>Examples</title>
+
+  <para>On Linux or Unix systems, you might use:
+
+<programlisting>
+archive_command = 'cp %p .../archive/%f'
+
+restore_command = 'pg_standby -d -s 2 -t /tmp/pgsql.trigger.5442 .../archive %f %p %r 2>>standby.log'
+
+recovery_end_command = 'rm -f /tmp/pgsql.trigger.5442'
+</programlisting>
+   where the archive directory is physically located on the standby server,
+   so that the <varname>archive_command</varname> is accessing it across NFS,
+   but the files are local to the standby (enabling use of <literal>ln</literal>).
+   This will:
+  <itemizedlist>
+   <listitem>
+    <para>
+     produce debugging output in <filename>standby.log</filename>
+    </para>
+   </listitem>
+   <listitem>
+    <para>
+     sleep for 2 seconds between checks for next WAL file availability
+    </para>
+   </listitem>
+   <listitem>
+    <para>
+     stop waiting only when a trigger file called
+     <filename>/tmp/pgsql.trigger.5442</filename> appears,
+     and perform failover according to its content
+    </para>
+   </listitem>
+   <listitem>
+    <para>
+     remove the trigger file when recovery ends
+    </para>
+   </listitem>
+   <listitem>
+    <para>
+     remove no-longer-needed files from the archive directory
+    </para>
+   </listitem>
+  </itemizedlist>
+  </para>
+
+  <para>On Windows, you might use:
+
+<programlisting>
+archive_command = 'copy %p ...\\archive\\%f'
+
+restore_command = 'pg_standby -d -s 5 -t C:\pgsql.trigger.5442 ...\archive %f %p %r 2>>standby.log'
+
+recovery_end_command = 'del C:\pgsql.trigger.5442'
+</programlisting>
+   Note that backslashes need to be doubled in the
+   <varname>archive_command</varname>, but <emphasis>not</emphasis> in the
+   <varname>restore_command</varname> or <varname>recovery_end_command</varname>.
+   This will:
+  <itemizedlist>
+   <listitem>
+    <para>
+     use the <literal>copy</literal> command to restore WAL files from archive
+    </para>
+   </listitem>
+   <listitem>
+    <para>
+     produce debugging output in <filename>standby.log</filename>
+    </para>
+   </listitem>
+   <listitem>
+    <para>
+     sleep for 5 seconds between checks for next WAL file availability
+    </para>
+   </listitem>
+   <listitem>
+    <para>
+     stop waiting only when a trigger file called
+     <filename>C:\pgsql.trigger.5442</filename> appears,
+     and perform failover according to its content
+    </para>
+   </listitem>
+   <listitem>
+    <para>
+     remove the trigger file when recovery ends
+    </para>
+   </listitem>
+   <listitem>
+    <para>
+     remove no-longer-needed files from the archive directory
+    </para>
+   </listitem>
+  </itemizedlist>
+  </para>
+
+  <para>
+   The <literal>copy</literal> command on Windows sets the final file size
+   before the file is completely copied, which would ordinarily confuse
+   <application>pg_standby</application>.  Therefore
+   <application>pg_standby</application> waits <replaceable>sleeptime</replaceable>
+   seconds once it sees the proper file size.  GNUWin32's <literal>cp</literal>
+   sets the file size only after the file copy is complete.
+  </para>
+
+  <para>
+   Since the Windows example uses <literal>copy</literal> at both ends, either
+   or both servers might be accessing the archive directory across the
+   network.
+  </para>
+
+ </refsect1>
+
+ <refsect1>
+  <title>Author</title>
+
+  <para>
+   Simon Riggs <email>simon@2ndquadrant.com</email>
+  </para>
+ </refsect1>
+
+ <refsect1>
+  <title>See Also</title>
+
+  <simplelist type="inline">
+   <member><xref linkend="pgarchivecleanup"/></member>
+  </simplelist>
+ </refsect1>
+</refentry>