From 3229db2d42969a4cc6434cb612ca03a19e661b43 Mon Sep 17 00:00:00 2001
From: Heikki Linnakangas <heikki.linnakangas@iki.fi>
Date: Mon, 22 Feb 2010 11:47:30 +0000
Subject: [PATCH] Move documentation of all recovery.conf option to a new
chapter. They used to be scattered between the "backup and restore" and
"streaming replication" chapters.
---
doc/src/sgml/backup.sgml | 160 +------------------
doc/src/sgml/filelist.sgml | 3 +-
doc/src/sgml/high-availability.sgml | 78 +---------
doc/src/sgml/postgres.sgml | 3 +-
doc/src/sgml/recovery-config.sgml | 233 ++++++++++++++++++++++++++++
5 files changed, 247 insertions(+), 230 deletions(-)
create mode 100644 doc/src/sgml/recovery-config.sgml
diff --git a/doc/src/sgml/backup.sgml b/doc/src/sgml/backup.sgml
index cab4b4545e8..feadf2b1d02 100644
--- a/doc/src/sgml/backup.sgml
+++ b/doc/src/sgml/backup.sgml
@@ -1,4 +1,4 @@
-<!-- $PostgreSQL: pgsql/doc/src/sgml/backup.sgml,v 2.142 2010/02/19 00:15:25 momjian Exp $ -->
+<!-- $PostgreSQL: pgsql/doc/src/sgml/backup.sgml,v 2.143 2010/02/22 11:47:30 heikki Exp $ -->
<chapter id="backup">
<title>Backup and Restore</title>
@@ -955,7 +955,7 @@ SELECT pg_stop_backup();
<listitem>
<para>
Create a recovery command file <filename>recovery.conf</> in the cluster
- data directory (see <xref linkend="recovery-config-settings">). You might
+ data directory (see <xref linkend="recovery-config">). You might
also want to temporarily modify <filename>pg_hba.conf</> to prevent
ordinary users from connecting until you are sure the recovery was successful.
</para>
@@ -1076,162 +1076,6 @@ restore_command = 'cp /mnt/server/archivedir/%f %p'
WAL data need not be scanned again.
</para>
-
- <sect3 id="recovery-config-settings" xreflabel="Recovery Settings">
- <title>Recovery Settings</title>
-
- <para>
- These settings can only be made in the <filename>recovery.conf</>
- file, and apply only for the duration of the recovery. (A sample file,
- <filename>share/recovery.conf.sample</>, exists in the installation's
- <filename>share/</> directory.) They must be
- reset for any subsequent recovery you wish to perform. They cannot be
- changed once recovery has begun.
- The parameters for streaming replication are described in <xref
- linkend="replication-config-settings">.
- </para>
-
- <variablelist>
-
- <varlistentry id="restore-command" xreflabel="restore_command">
- <term><varname>restore_command</varname> (<type>string</type>)</term>
- <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="recovery-end-command" xreflabel="recovery_end_command">
- <term><varname>recovery_end_command</varname> (<type>string</type>)</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. 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 restart from the current restore. <literal>%r</> 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 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>
-
- <varlistentry id="recovery-target-time" xreflabel="recovery_target_time">
- <term><varname>recovery_target_time</varname>
- (<type>timestamp</type>)
- </term>
- <listitem>
- <para>
- This parameter specifies the time stamp up to which recovery
- will proceed.
- At most one of <varname>recovery_target_time</> and
- <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>
- <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</> and
- <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>
- <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>
- <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. 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>
-
- </variablelist>
-
- </sect3>
-
</sect2>
<sect2 id="backup-timelines">
diff --git a/doc/src/sgml/filelist.sgml b/doc/src/sgml/filelist.sgml
index 732c41fb7b3..57f3af2c13d 100644
--- a/doc/src/sgml/filelist.sgml
+++ b/doc/src/sgml/filelist.sgml
@@ -1,4 +1,4 @@
-<!-- $PostgreSQL: pgsql/doc/src/sgml/filelist.sgml,v 1.66 2010/02/17 04:19:37 tgl Exp $ -->
+<!-- $PostgreSQL: pgsql/doc/src/sgml/filelist.sgml,v 1.67 2010/02/22 11:47:30 heikki Exp $ -->
<!entity history SYSTEM "history.sgml">
<!entity info SYSTEM "info.sgml">
@@ -42,6 +42,7 @@
<!entity manage-ag SYSTEM "manage-ag.sgml">
<!entity monitoring SYSTEM "monitoring.sgml">
<!entity regress SYSTEM "regress.sgml">
+<!entity recovery-config SYSTEM "recovery-config.sgml">
<!entity runtime SYSTEM "runtime.sgml">
<!entity config SYSTEM "config.sgml">
<!entity user-manag SYSTEM "user-manag.sgml">
diff --git a/doc/src/sgml/high-availability.sgml b/doc/src/sgml/high-availability.sgml
index 535321da392..5d7057daa15 100644
--- a/doc/src/sgml/high-availability.sgml
+++ b/doc/src/sgml/high-availability.sgml
@@ -1,4 +1,4 @@
-<!-- $PostgreSQL: pgsql/doc/src/sgml/high-availability.sgml,v 1.48 2010/02/20 10:07:27 sriggs Exp $ -->
+<!-- $PostgreSQL: pgsql/doc/src/sgml/high-availability.sgml,v 1.49 2010/02/22 11:47:30 heikki Exp $ -->
<chapter id="high-availability">
<title>High Availability, Load Balancing, and Replication</title>
@@ -853,77 +853,15 @@ if (!triggered)
<listitem>
<para>
Create a recovery command file <filename>recovery.conf</> in the data
- directory on the standby server.
+ directory on the standby server. Set <varname>restore_command</varname>
+ as you would in normal recovery from a continuous archiving backup
+ (see <xref linkend="backup-pitr-recovery">). <literal>pg_standby</> or
+ similar tools that wait for the next WAL file to arrive cannot be used
+ with streaming replication, as the server handles retries and waiting
+ itself. Enable <varname>standby_mode</varname>. Set
+ <varname>primary_conninfo</varname> to point to the primary server.
</para>
- <variablelist id="replication-config-settings" xreflabel="Replication Settings">
- <varlistentry id="standby-mode" xreflabel="standby_mode">
- <term><varname>standby_mode</varname> (<type>boolean</type>)</term>
- <listitem>
- <para>
- Specifies whether to start the <productname>PostgreSQL</> server as
- a standby. If this parameter is <literal>on</>, the server will
- not end recovery when the end of archived WAL is reached, but
- will keep trying to continue recovery using <varname>restore_command</>
- and by connecting to the primary server as specified by the
- <varname>primary_conninfo</> setting.
- </para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term><varname>restore_command</varname> (<type>string</type>)</term>
- <term><varname>restore_end_command</varname> (<type>string</type>)</term>
- <listitem>
- <para>
- With <varname>standby_mode</> enabled, <varname>restore_command</>
- (and <varname>restore_end_command</>) should be set to a
- simple command or script like in PITR. <literal>pg_standby</> or similar tools
- that wait for the next WAL file to arrive cannot be used with
- streaming replication, as the server handles retries and waiting
- itself. Set <varname>restore_command</> as you would if you were
- recovering using a Continuous archiving backup (see <xref linkend="backup-pitr-recovery">).
- </para>
- </listitem>
- </varlistentry>
- <varlistentry id="primary-conninfo" xreflabel="primary_conninfo">
- <term><varname>primary_conninfo</varname> (<type>string</type>)</term>
- <listitem>
- <para>
- Specifies a connection string to be used for the standby server
- to connect with the primary. This string is in the same format as
- 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 built-in replication requires that a host name (or host address)
- or port number which the primary server listens on be
- specified in this string. Also ensure that a role with
- the <literal>SUPERUSER</> and <literal>LOGIN</> privileges on the
- primary is set (see
- <xref linkend="streaming-replication-authentication">). Note that
- the password needs to be set if the primary demands password
- authentication.
- </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>
- <listitem>
- <para>
- Specifies a trigger file whose presence ends recovery in the
- standby. If no trigger file is specified, the standby never exits
- recovery.
- This setting has no effect if <varname>standby_mode</> is <literal>off</>.
- </para>
- </listitem>
- </varlistentry>
- </variablelist>
</listitem>
<listitem>
<para>
diff --git a/doc/src/sgml/postgres.sgml b/doc/src/sgml/postgres.sgml
index caebed54447..3f2a6e0efc2 100644
--- a/doc/src/sgml/postgres.sgml
+++ b/doc/src/sgml/postgres.sgml
@@ -1,4 +1,4 @@
-<!-- $PostgreSQL: pgsql/doc/src/sgml/postgres.sgml,v 1.90 2009/08/04 22:04:37 petere Exp $ -->
+<!-- $PostgreSQL: pgsql/doc/src/sgml/postgres.sgml,v 1.91 2010/02/22 11:47:30 heikki Exp $ -->
<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook V4.2//EN" [
@@ -155,6 +155,7 @@
&maintenance;
&backup;
&high-availability;
+ &recovery-config;
&monitoring;
&diskusage;
&wal;
diff --git a/doc/src/sgml/recovery-config.sgml b/doc/src/sgml/recovery-config.sgml
new file mode 100644
index 00000000000..b892d93e056
--- /dev/null
+++ b/doc/src/sgml/recovery-config.sgml
@@ -0,0 +1,233 @@
+<!-- $PostgreSQL: pgsql/doc/src/sgml/recovery-config.sgml,v 2.1 2010/02/22 11:47:30 heikki Exp $ -->
+
+<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
+ <filename>recovery.conf</> file. They apply only for the duration of
+ the recovery. (A sample file, <filename>share/recovery.conf.sample</>,
+ exists in the installation's <filename>share/</> directory.) They must
+ be reset for any subsequent recovery you wish to perform. They cannot
+ be changed once recovery has begun.
+ </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>
+ <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="recovery-end-command" xreflabel="recovery_end_command">
+ <term><varname>recovery_end_command</varname> (<type>string</type>)</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. 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 restart from the current restore. <literal>%r</> 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 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-time" xreflabel="recovery_target_time">
+ <term><varname>recovery_target_time</varname>
+ (<type>timestamp</type>)
+ </term>
+ <listitem>
+ <para>
+ This parameter specifies the time stamp up to which recovery
+ will proceed.
+ At most one of <varname>recovery_target_time</> and
+ <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>
+ <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</> and
+ <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>
+ <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>
+ <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. 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>
+
+ </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>
+ <listitem>
+ <para>
+ Specifies whether to start the <productname>PostgreSQL</> server as
+ a standby. If this parameter is <literal>on</>, the server will
+ not end recovery when the end of archived WAL is reached, but
+ will keep trying to continue recovery using <varname>restore_command</>
+ and 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>
+ <listitem>
+ <para>
+ Specifies a connection string to be used for the standby server
+ to connect with the primary. This string is in the same format as
+ 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 built-in replication requires that a host name (or host address)
+ or port number which the primary server listens on be
+ specified in this string. Also ensure that a role with
+ the <literal>SUPERUSER</> and <literal>LOGIN</> privileges on the
+ primary is set (see
+ <xref linkend="streaming-replication-authentication">). Note that
+ the password needs to be set if the primary demands password
+ authentication.
+ </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>
+ <listitem>
+ <para>
+ Specifies a trigger file whose presence ends recovery in the
+ standby. If no trigger file is specified, the standby never exits
+ recovery.
+ This setting has no effect if <varname>standby_mode</> is <literal>off</>.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ </variablelist>
+ </sect1>
+
+</chapter>
--
GitLab