mirror of
https://github.com/postgres/postgres.git
synced 2025-06-01 00:01:20 -04:00
00c5f55061
superuser doesn't have doesn't make much sense, as a superuser can do whatever he wants through other means, anyway. So instead of granting replication privilege to superusers in CREATE USER time by default, allow replication connection from superusers whether or not they have the replication privilege. Patch by Noah Misch, per discussion on bug report #6264
363 lines
15 KiB
Plaintext
363 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
|
|
accepted by the libpq <function>PQconnectdb</function> function,
|
|
described in <xref linkend="libpq-connect">. 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>
|