mirror of
https://git.postgresql.org/git/postgresql.git
synced 2024-09-10 05:59:23 +02:00
Before, some places didn't document the short options (-? and -V), some documented both, some documented nothing, and they were listed in various orders. Now this is hopefully more consistent and complete.
395 lines
13 KiB
Plaintext
395 lines
13 KiB
Plaintext
<!-- doc/src/sgml/pgstandby.sgml -->
|
|
|
|
<refentry id="pgstandby">
|
|
<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>
|
|
|
|
<indexterm zone="pgstandby">
|
|
<primary>pg_standby</primary>
|
|
</indexterm>
|
|
|
|
<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>xlogfilepath</replaceable></arg>
|
|
<arg choice="opt"><replaceable>restartwalfile</replaceable></arg>
|
|
</cmdsynopsis>
|
|
</refsynopsisdiv>
|
|
|
|
<refsect1>
|
|
<title>Description</title>
|
|
|
|
<para>
|
|
<application>pg_standby</> supports creation of a <quote>warm standby</>
|
|
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</> is designed to be a waiting
|
|
<varname>restore_command</>, 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</>, put this into its
|
|
<filename>recovery.conf</filename> configuration file:
|
|
<programlisting>
|
|
restore_command = 'pg_standby <replaceable>archiveDir</> %f %p %r'
|
|
</programlisting>
|
|
where <replaceable>archiveDir</> is the directory from which WAL segment
|
|
files should be restored.
|
|
</para>
|
|
<para>
|
|
If <replaceable>restartwalfile</> is specified, normally by using the
|
|
<literal>%r</literal> macro, then all WAL files logically preceding this
|
|
file 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.
|
|
</para>
|
|
<para>
|
|
<application>pg_standby</application> assumes that
|
|
<replaceable>archivelocation</> is a directory readable by the
|
|
server-owning user. If <replaceable>restartwalfile</> (or <literal>-k</>)
|
|
is specified,
|
|
the <replaceable>archivelocation</> directory must be writable too.
|
|
</para>
|
|
<para>
|
|
There are two ways to fail over to a <quote>warm standby</> 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</>, 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</> into it.
|
|
<application>pg_standby</> 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</> or <literal>copy</> 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</>.
|
|
</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</> as of
|
|
<productname>PostgreSQL</> 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</></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>num_retries</>
|
|
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</></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</></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</>.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term><option>-V</></term>
|
|
<term><option>--version</></term>
|
|
<listitem>
|
|
<para>
|
|
Print the <application>pg_standby</application> version and exit.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term><option>-w</option> <replaceable>maxwaittime</></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>-?</></term>
|
|
<term><option>--help</></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</> 8.2 and later.
|
|
</para>
|
|
<para>
|
|
<productname>PostgreSQL</> 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</> 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</> 8.4 provides the
|
|
<varname>recovery_end_command</> 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</> is accessing it across NFS,
|
|
but the files are local to the standby (enabling use of <literal>ln</>).
|
|
This will:
|
|
<itemizedlist>
|
|
<listitem>
|
|
<para>
|
|
produce debugging output in <filename>standby.log</>
|
|
</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</> 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</>, but <emphasis>not</emphasis> in the
|
|
<varname>restore_command</> or <varname>recovery_end_command</>.
|
|
This will:
|
|
<itemizedlist>
|
|
<listitem>
|
|
<para>
|
|
use the <literal>copy</> command to restore WAL files from archive
|
|
</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>
|
|
produce debugging output in <filename>standby.log</>
|
|
</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</> 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</> 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 <literal>sleeptime</>
|
|
seconds once it sees the proper file size. GNUWin32's <literal>cp</>
|
|
sets the file size only after the file copy is complete.
|
|
</para>
|
|
|
|
<para>
|
|
Since the Windows example uses <literal>copy</> 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>
|