362 lines
15 KiB
Plaintext
362 lines
15 KiB
Plaintext
<!-- doc/src/sgml/recovery-config.sgml -->
|
|
|
|
<chapter id="recovery-config">
|
|
<title>Recovery Configuration</title>
|
|
|
|
<indexterm>
|
|
<primary>configuration</primary>
|
|
<secondary>of recovery</secondary>
|
|
<tertiary>of a standby server</tertiary>
|
|
</indexterm>
|
|
|
|
<para>
|
|
This chapter describes the settings available in the
|
|
<filename>recovery.conf</><indexterm><primary>recovery.conf</></>
|
|
file. They apply only for the duration of the
|
|
recovery. They must be reset for any subsequent recovery you wish to
|
|
perform. They cannot be changed once recovery has begun.
|
|
</para>
|
|
|
|
<para>
|
|
Settings in <filename>recovery.conf</> are specified in the format
|
|
<literal>name = 'value'</>. One parameter is specified per line.
|
|
Hash marks (<literal>#</literal>) designate the rest of the
|
|
line as a comment. To embed a single quote in a parameter
|
|
value, write two quotes (<literal>''</>).
|
|
</para>
|
|
|
|
<para>
|
|
A sample file, <filename>share/recovery.conf.sample</>,
|
|
is provided in the installation's <filename>share/</> directory.
|
|
</para>
|
|
|
|
<sect1 id="archive-recovery-settings">
|
|
|
|
<title>Archive Recovery Settings</title>
|
|
<variablelist>
|
|
|
|
<varlistentry id="restore-command" xreflabel="restore_command">
|
|
<term><varname>restore_command</varname> (<type>string</type>)</term>
|
|
<indexterm>
|
|
<primary><varname>restore_command</> recovery parameter</primary>
|
|
</indexterm>
|
|
<listitem>
|
|
<para>
|
|
The shell command to execute to retrieve an archived segment of
|
|
the WAL file series. This parameter is required for archive recovery,
|
|
but optional for streaming replication.
|
|
Any <literal>%f</> in the string is
|
|
replaced by the name of the file to retrieve from the archive,
|
|
and any <literal>%p</> is replaced by the copy destination path name
|
|
on the server.
|
|
(The path name is relative to the current working directory,
|
|
i.e., the cluster's data directory.)
|
|
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
|
|
restarting from the current restore. <literal>%r</> is typically only
|
|
used by warm-standby configurations
|
|
(see <xref linkend="warm-standby">).
|
|
Write <literal>%%</> to embed an actual <literal>%</> character.
|
|
</para>
|
|
|
|
<para>
|
|
It is important for the command to return a zero exit status
|
|
only if it succeeds. The command <emphasis>will</> be asked for file
|
|
names that are not present in the archive; it must return nonzero
|
|
when so asked. Examples:
|
|
<programlisting>
|
|
restore_command = 'cp /mnt/server/archivedir/%f "%p"'
|
|
restore_command = 'copy "C:\\server\\archivedir\\%f" "%p"' # Windows
|
|
</programlisting>
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry id="archive-cleanup-command" xreflabel="archive_cleanup_command">
|
|
<term><varname>archive_cleanup_command</varname> (<type>string</type>)</term>
|
|
<indexterm>
|
|
<primary><varname>archive_cleanup_command</> recovery parameter</primary>
|
|
</indexterm>
|
|
<listitem>
|
|
<para>
|
|
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 <xref linkend="pgarchivecleanup"> module
|
|
is often used in <varname>archive_cleanup_command</> for
|
|
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
|
|
message will be written.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry id="recovery-end-command" xreflabel="recovery_end_command">
|
|
<term><varname>recovery_end_command</varname> (<type>string</type>)</term>
|
|
<indexterm>
|
|
<primary><varname>recovery_end_command</> recovery parameter</primary>
|
|
</indexterm>
|
|
<listitem>
|
|
<para>
|
|
This parameter specifies a shell command that will be executed once only
|
|
at the end of recovery. This parameter is optional. The purpose of the
|
|
<varname>recovery_end_command</> is to provide a mechanism for cleanup
|
|
following replication or recovery.
|
|
Any <literal>%r</> is replaced by the name of the file containing the
|
|
last valid restart point, like in <xref linkend="archive-cleanup-command">.
|
|
</para>
|
|
<para>
|
|
If the command returns a non-zero exit status then a WARNING log
|
|
message will be written and the database will proceed to start up
|
|
anyway. An exception is that if the command was terminated by a
|
|
signal, the database will not proceed with startup.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
</variablelist>
|
|
|
|
</sect1>
|
|
|
|
<sect1 id="recovery-target-settings">
|
|
|
|
<title>Recovery Target Settings</title>
|
|
<variablelist>
|
|
|
|
<varlistentry id="recovery-target-name" xreflabel="recovery_target_name">
|
|
<term><varname>recovery_target_name</varname>
|
|
(<type>string</type>)
|
|
</term>
|
|
<indexterm>
|
|
<primary><varname>recovery_target_name</> recovery parameter</primary>
|
|
</indexterm>
|
|
<listitem>
|
|
<para>
|
|
This parameter specifies the named restore point, created with
|
|
<function>pg_create_restore_point()</> to which recovery will proceed.
|
|
At most one of <varname>recovery_target_name</>,
|
|
<xref linkend="recovery-target-time"> or
|
|
<xref linkend="recovery-target-xid"> can be specified. The default is to
|
|
recover to the end of the WAL log.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry id="recovery-target-time" xreflabel="recovery_target_time">
|
|
<term><varname>recovery_target_time</varname>
|
|
(<type>timestamp</type>)
|
|
</term>
|
|
<indexterm>
|
|
<primary><varname>recovery_target_time</> recovery parameter</primary>
|
|
</indexterm>
|
|
<listitem>
|
|
<para>
|
|
This parameter specifies the time stamp up to which recovery
|
|
will proceed.
|
|
At most one of <varname>recovery_target_time</>,
|
|
<xref linkend="recovery-target-name"> or
|
|
<xref linkend="recovery-target-xid"> can be specified.
|
|
The default is to recover to the end of the WAL log.
|
|
The precise stopping point is also influenced by
|
|
<xref linkend="recovery-target-inclusive">.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry id="recovery-target-xid" xreflabel="recovery_target_xid">
|
|
<term><varname>recovery_target_xid</varname> (<type>string</type>)</term>
|
|
<indexterm>
|
|
<primary><varname>recovery_target_xid</> recovery parameter</primary>
|
|
</indexterm>
|
|
<listitem>
|
|
<para>
|
|
This parameter specifies the transaction ID up to which recovery
|
|
will proceed. Keep in mind
|
|
that while transaction IDs are assigned sequentially at transaction
|
|
start, transactions can complete in a different numeric order.
|
|
The transactions that will be recovered are those that committed
|
|
before (and optionally including) the specified one.
|
|
At most one of <varname>recovery_target_xid</>,
|
|
<xref linkend="recovery-target-name"> or
|
|
<xref linkend="recovery-target-time"> can be specified.
|
|
The default is to recover to the end of the WAL log.
|
|
The precise stopping point is also influenced by
|
|
<xref linkend="recovery-target-inclusive">.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry id="recovery-target-inclusive"
|
|
xreflabel="recovery_target_inclusive">
|
|
<term><varname>recovery_target_inclusive</varname>
|
|
(<type>boolean</type>)
|
|
</term>
|
|
<indexterm>
|
|
<primary><varname>recovery_target_inclusive</> recovery parameter</primary>
|
|
</indexterm>
|
|
<listitem>
|
|
<para>
|
|
Specifies whether we stop just after the specified recovery target
|
|
(<literal>true</literal>), or just before the recovery target
|
|
(<literal>false</literal>).
|
|
Applies to both <xref linkend="recovery-target-time">
|
|
and <xref linkend="recovery-target-xid">, whichever one is
|
|
specified for this recovery. This indicates whether transactions
|
|
having exactly the target commit time or ID, respectively, will
|
|
be included in the recovery. Default is <literal>true</>.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry id="recovery-target-timeline"
|
|
xreflabel="recovery_target_timeline">
|
|
<term><varname>recovery_target_timeline</varname>
|
|
(<type>string</type>)
|
|
</term>
|
|
<indexterm>
|
|
<primary><varname>recovery_target_timeline</> recovery parameter</primary>
|
|
</indexterm>
|
|
<listitem>
|
|
<para>
|
|
Specifies recovering into a particular timeline. The default is
|
|
to recover along the same timeline that was current when the
|
|
base backup was taken. Setting this to <literal>latest</> recovers
|
|
to the latest timeline found in the archive, which is useful in
|
|
a standby server. Other than that you only need to set this parameter
|
|
in complex re-recovery situations, where you need to return to
|
|
a state that itself was reached after a point-in-time recovery.
|
|
See <xref linkend="backup-timelines"> for discussion.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry id="pause-at-recovery-target"
|
|
xreflabel="pause_at_recovery_target">
|
|
<term><varname>pause_at_recovery_target</varname>
|
|
(<type>boolean</type>)
|
|
</term>
|
|
<indexterm>
|
|
<primary><varname>pause_at_recovery_target</> recovery parameter</primary>
|
|
</indexterm>
|
|
<listitem>
|
|
<para>
|
|
Specifies whether recovery should pause when the recovery target
|
|
is reached. The default is true.
|
|
This is intended to allow queries to be executed against the
|
|
database to check if this recovery target is the most desirable
|
|
point for recovery. The paused state can be resumed by using
|
|
<function>pg_xlog_replay_resume()</> (See
|
|
<xref linkend="functions-recovery-control-table">), which then
|
|
causes recovery to end. If this recovery target is not the
|
|
desired stopping point, then shutdown the server, change the
|
|
recovery target settings to a later target and restart to
|
|
continue recovery.
|
|
</para>
|
|
<para>
|
|
This setting has no effect if <xref linkend="guc-hot-standby"> is not
|
|
enabled, or if no recovery target is set.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
</variablelist>
|
|
</sect1>
|
|
|
|
<sect1 id="standby-settings">
|
|
|
|
<title>Standby Server Settings</title>
|
|
<variablelist>
|
|
|
|
<varlistentry id="standby-mode" xreflabel="standby_mode">
|
|
<term><varname>standby_mode</varname> (<type>boolean</type>)</term>
|
|
<indexterm>
|
|
<primary><varname>standby_mode</> recovery parameter</primary>
|
|
</indexterm>
|
|
<listitem>
|
|
<para>
|
|
Specifies whether to start the <productname>PostgreSQL</> server as
|
|
a standby. If this parameter is <literal>on</>, the server will
|
|
not stop recovery when the end of archived WAL is reached, but
|
|
will keep trying to continue recovery by fetching new WAL segments
|
|
using <varname>restore_command</>
|
|
and/or by connecting to the primary server as specified by the
|
|
<varname>primary_conninfo</> setting.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
<varlistentry id="primary-conninfo" xreflabel="primary_conninfo">
|
|
<term><varname>primary_conninfo</varname> (<type>string</type>)</term>
|
|
<indexterm>
|
|
<primary><varname>primary_conninfo</> recovery parameter</primary>
|
|
</indexterm>
|
|
<listitem>
|
|
<para>
|
|
Specifies a connection string to be used for the standby server
|
|
to connect with the primary. This string is in the format
|
|
described in <xref linkend="libpq-connstring">. If any option is
|
|
unspecified in this string, then the corresponding environment
|
|
variable (see <xref linkend="libpq-envars">) is checked. If the
|
|
environment variable is not set either, then
|
|
defaults are used.
|
|
</para>
|
|
<para>
|
|
The connection string should specify the host name (or address)
|
|
of the primary server, as well as the port number if it is not
|
|
the same as the standby server's default.
|
|
Also specify a user name corresponding to a suitably-privileged role
|
|
on the primary (see
|
|
<xref linkend="streaming-replication-authentication">).
|
|
A password needs to be provided too, if the primary demands password
|
|
authentication. It can be provided in the
|
|
<varname>primary_conninfo</varname> string, or in a separate
|
|
<filename>~/.pgpass</> file on the standby server (use
|
|
<literal>replication</> as the database name).
|
|
Do not specify a database name in the
|
|
<varname>primary_conninfo</varname> string.
|
|
</para>
|
|
<para>
|
|
This setting has no effect if <varname>standby_mode</> is <literal>off</>.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
<varlistentry id="trigger-file" xreflabel="trigger_file">
|
|
<term><varname>trigger_file</varname> (<type>string</type>)</term>
|
|
<indexterm>
|
|
<primary><varname>trigger_file</> recovery parameter</primary>
|
|
</indexterm>
|
|
<listitem>
|
|
<para>
|
|
Specifies a trigger file whose presence ends recovery in the
|
|
standby. Even if this value is not set, you can still promote
|
|
the standby using <command>pg_ctl promote</>.
|
|
This setting has no effect if <varname>standby_mode</> is <literal>off</>.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
</variablelist>
|
|
</sect1>
|
|
|
|
</chapter>
|