diff options
Diffstat (limited to 'doc/src/sgml/pgstandby.sgml')
| -rw-r--r-- | doc/src/sgml/pgstandby.sgml | 394 |
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> |