509 lines
22 KiB
Plaintext
509 lines
22 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>)
|
|
<indexterm>
|
|
<primary><varname>restore_command</> recovery parameter</primary>
|
|
</indexterm>
|
|
</term>
|
|
<listitem>
|
|
<para>
|
|
The local 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>
|
|
An exception is that if the command was terminated by a signal (other
|
|
than <systemitem>SIGTERM</systemitem>, which is used as part of a
|
|
database server shutdown) or an error by the shell (such as command
|
|
not found), then recovery will abort and the server will not start up.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry id="archive-cleanup-command" xreflabel="archive_cleanup_command">
|
|
<term><varname>archive_cleanup_command</varname> (<type>string</type>)
|
|
<indexterm>
|
|
<primary><varname>archive_cleanup_command</> recovery parameter</primary>
|
|
</indexterm>
|
|
</term>
|
|
<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 nonzero exit status then a warning log
|
|
message will be written. An exception is that if the command was
|
|
terminated by a signal or an error by the shell (such as command not
|
|
found), a fatal error will be raised.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry id="recovery-end-command" xreflabel="recovery_end_command">
|
|
<term><varname>recovery_end_command</varname> (<type>string</type>)
|
|
<indexterm>
|
|
<primary><varname>recovery_end_command</> recovery parameter</primary>
|
|
</indexterm>
|
|
</term>
|
|
<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 nonzero 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 or an error by the shell (such as command not found), the
|
|
database will not proceed with startup.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
</variablelist>
|
|
|
|
</sect1>
|
|
|
|
<sect1 id="recovery-target-settings">
|
|
|
|
<title>Recovery Target Settings</title>
|
|
|
|
<para>
|
|
By default, recovery will recover to the end of the WAL log. The
|
|
following parameters can be used to specify an earlier stopping point.
|
|
At most one of <varname>recovery_target</>,
|
|
<varname>recovery_target_lsn</>, <varname>recovery_target_name</>,
|
|
<varname>recovery_target_time</>, or <varname>recovery_target_xid</>
|
|
can be used; if more than one of these is specified in the configuration
|
|
file, the last entry will be used.
|
|
</para>
|
|
|
|
<variablelist>
|
|
<varlistentry id="recovery-target" xreflabel="recovery_target">
|
|
<term><varname>recovery_target</varname><literal> = 'immediate'</literal>
|
|
<indexterm>
|
|
<primary><varname>recovery_target</> recovery parameter</primary>
|
|
</indexterm>
|
|
</term>
|
|
<listitem>
|
|
<para>
|
|
This parameter specifies that recovery should end as soon as a
|
|
consistent state is reached, i.e. as early as possible. When restoring
|
|
from an online backup, this means the point where taking the backup
|
|
ended.
|
|
</para>
|
|
<para>
|
|
Technically, this is a string parameter, but <literal>'immediate'</>
|
|
is currently the only allowed value.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry id="recovery-target-name" xreflabel="recovery_target_name">
|
|
<term><varname>recovery_target_name</varname> (<type>string</type>)
|
|
<indexterm>
|
|
<primary><varname>recovery_target_name</> recovery parameter</primary>
|
|
</indexterm>
|
|
</term>
|
|
<listitem>
|
|
<para>
|
|
This parameter specifies the named restore point (created with
|
|
<function>pg_create_restore_point()</>) to which recovery will proceed.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry id="recovery-target-time" xreflabel="recovery_target_time">
|
|
<term><varname>recovery_target_time</varname> (<type>timestamp</type>)
|
|
<indexterm>
|
|
<primary><varname>recovery_target_time</> recovery parameter</primary>
|
|
</indexterm>
|
|
</term>
|
|
<listitem>
|
|
<para>
|
|
This parameter specifies the time stamp up to which recovery
|
|
will proceed.
|
|
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>)
|
|
<indexterm>
|
|
<primary><varname>recovery_target_xid</> recovery parameter</primary>
|
|
</indexterm>
|
|
</term>
|
|
<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.
|
|
The precise stopping point is also influenced by
|
|
<xref linkend="recovery-target-inclusive">.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry id="recovery-target-lsn" xreflabel="recovery_target_lsn">
|
|
<term><varname>recovery_target_lsn</varname> (<type>pg_lsn</type>)
|
|
<indexterm>
|
|
<primary><varname>recovery_target_lsn</> recovery parameter</primary>
|
|
</indexterm>
|
|
</term>
|
|
<listitem>
|
|
<para>
|
|
This parameter specifies the LSN of the transaction log location up
|
|
to which recovery will proceed. The precise stopping point is also
|
|
influenced by <xref linkend="recovery-target-inclusive">. This
|
|
parameter is parsed using the system data type
|
|
<link linkend="datatype-pg-lsn"><type>pg_lsn</></link>.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
</variablelist>
|
|
|
|
<para>
|
|
The following options further specify the recovery target, and affect
|
|
what happens when the target is reached:
|
|
</para>
|
|
|
|
<variablelist>
|
|
<varlistentry id="recovery-target-inclusive"
|
|
xreflabel="recovery_target_inclusive">
|
|
<term><varname>recovery_target_inclusive</varname> (<type>boolean</type>)
|
|
<indexterm>
|
|
<primary><varname>recovery_target_inclusive</> recovery parameter</primary>
|
|
</indexterm>
|
|
</term>
|
|
<listitem>
|
|
<para>
|
|
Specifies whether to stop just after the specified recovery target
|
|
(<literal>true</literal>), or just before the recovery target
|
|
(<literal>false</literal>).
|
|
Applies when either <xref linkend="recovery-target-time">
|
|
or <xref linkend="recovery-target-xid"> is specified.
|
|
This setting controls 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>)
|
|
<indexterm>
|
|
<primary><varname>recovery_target_timeline</> recovery parameter</primary>
|
|
</indexterm>
|
|
</term>
|
|
<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="recovery-target-action"
|
|
xreflabel="recovery_target_action">
|
|
<term><varname>recovery_target_action</varname> (<type>enum</type>)
|
|
<indexterm>
|
|
<primary><varname>recovery_target_action</> recovery parameter</primary>
|
|
</indexterm>
|
|
</term>
|
|
<listitem>
|
|
<para>
|
|
Specifies what action the server should take once the recovery target is
|
|
reached. The default is <literal>pause</>, which means recovery will
|
|
be paused. <literal>promote</> means the recovery process will finish
|
|
and the server will start to accept connections.
|
|
Finally <literal>shutdown</> will stop the server after reaching the
|
|
recovery target.
|
|
</para>
|
|
<para>
|
|
The intended use of the <literal>pause</> setting is 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 shut down the server, change the
|
|
recovery target settings to a later target and restart to
|
|
continue recovery.
|
|
</para>
|
|
<para>
|
|
The <literal>shutdown</> setting is useful to have the instance ready
|
|
at the exact replay point desired. The instance will still be able to
|
|
replay more WAL records (and in fact will have to replay WAL records
|
|
since the last checkpoint next time it is started).
|
|
</para>
|
|
<para>
|
|
Note that because <filename>recovery.conf</> will not be renamed when
|
|
<varname>recovery_target_action</> is set to <literal>shutdown</>,
|
|
any subsequent start will end with immediate shutdown unless the
|
|
configuration is changed or the <filename>recovery.conf</> file is
|
|
removed manually.
|
|
</para>
|
|
<para>
|
|
This setting has no effect if no recovery target is set.
|
|
If <xref linkend="guc-hot-standby"> is not enabled, a setting of
|
|
<literal>pause</> will act the same as <literal>shutdown</>.
|
|
</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>)
|
|
<indexterm>
|
|
<primary><varname>standby_mode</> recovery parameter</primary>
|
|
</indexterm>
|
|
</term>
|
|
<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>)
|
|
<indexterm>
|
|
<primary><varname>primary_conninfo</> recovery parameter</primary>
|
|
</indexterm>
|
|
</term>
|
|
<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="primary-slot-name" xreflabel="primary_slot_name">
|
|
<term><varname>primary_slot_name</varname> (<type>string</type>)
|
|
<indexterm>
|
|
<primary><varname>primary_slot_name</> recovery parameter</primary>
|
|
</indexterm>
|
|
</term>
|
|
<listitem>
|
|
<para>
|
|
Optionally specifies an existing replication slot to be used when
|
|
connecting to the primary via streaming replication to control
|
|
resource removal on the upstream node
|
|
(see <xref linkend="streaming-replication-slots">).
|
|
This setting has no effect if <varname>primary_conninfo</> is not
|
|
set.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
<varlistentry id="trigger-file" xreflabel="trigger_file">
|
|
<term><varname>trigger_file</varname> (<type>string</type>)
|
|
<indexterm>
|
|
<primary><varname>trigger_file</> recovery parameter</primary>
|
|
</indexterm>
|
|
</term>
|
|
<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>
|
|
|
|
<varlistentry id="recovery-min-apply-delay" xreflabel="recovery_min_apply_delay">
|
|
<term><varname>recovery_min_apply_delay</varname> (<type>integer</type>)
|
|
<indexterm>
|
|
<primary><varname>recovery_min_apply_delay</> recovery parameter</primary>
|
|
</indexterm>
|
|
</term>
|
|
<listitem>
|
|
<para>
|
|
By default, a standby server restores WAL records from the
|
|
primary as soon as possible. It may be useful to have a time-delayed
|
|
copy of the data, offering opportunities to correct data loss errors.
|
|
This parameter allows you to delay recovery by a fixed period of time,
|
|
measured in milliseconds if no unit is specified. For example, if
|
|
you set this parameter to <literal>5min</literal>, the standby will
|
|
replay each transaction commit only when the system time on the standby
|
|
is at least five minutes past the commit time reported by the master.
|
|
</para>
|
|
<para>
|
|
It is possible that the replication delay between servers exceeds the
|
|
value of this parameter, in which case no delay is added.
|
|
Note that the delay is calculated between the WAL time stamp as written
|
|
on master and the current time on the standby. Delays in transfer
|
|
because of network lag or cascading replication configurations
|
|
may reduce the actual wait time significantly. If the system
|
|
clocks on master and standby are not synchronized, this may lead to
|
|
recovery applying records earlier than expected; but that is not a
|
|
major issue because useful settings of this parameter are much larger
|
|
than typical time deviations between servers.
|
|
</para>
|
|
<para>
|
|
The delay occurs only on WAL records for transaction commits.
|
|
Other records are replayed as quickly as possible, which
|
|
is not a problem because MVCC visibility rules ensure their effects
|
|
are not visible until the corresponding commit record is applied.
|
|
</para>
|
|
<para>
|
|
The delay occurs once the database in recovery has reached a consistent
|
|
state, until the standby is promoted or triggered. After that the standby
|
|
will end recovery without further waiting.
|
|
</para>
|
|
<para>
|
|
This parameter is intended for use with streaming replication deployments;
|
|
however, if the parameter is specified it will be honored in all cases.
|
|
|
|
<varname>hot_standby_feedback</> will be delayed by use of this feature
|
|
which could lead to bloat on the master; use both together with care.
|
|
|
|
<warning>
|
|
<para>
|
|
Synchronous replication is affected by this setting when <varname>synchronous_commit</varname>
|
|
is set to <literal>remote_apply</literal>; every <literal>COMMIT</literal>
|
|
will need to wait to be applied.
|
|
</para>
|
|
</warning>
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
</variablelist>
|
|
</sect1>
|
|
|
|
</chapter>
|