diff options
Diffstat (limited to 'doc/src')
| -rw-r--r-- | doc/src/sgml/backup.sgml | 22 | ||||
| -rw-r--r-- | doc/src/sgml/config.sgml | 515 | ||||
| -rw-r--r-- | doc/src/sgml/filelist.sgml | 1 | ||||
| -rw-r--r-- | doc/src/sgml/func.sgml | 2 | ||||
| -rw-r--r-- | doc/src/sgml/high-availability.sgml | 56 | ||||
| -rw-r--r-- | doc/src/sgml/pgstandby.sgml | 2 | ||||
| -rw-r--r-- | doc/src/sgml/postgres.sgml | 1 | ||||
| -rw-r--r-- | doc/src/sgml/recovery-config.sgml | 510 | ||||
| -rw-r--r-- | doc/src/sgml/ref/pg_basebackup.sgml | 7 | ||||
| -rw-r--r-- | doc/src/sgml/ref/pg_rewind.sgml | 8 | ||||
| -rw-r--r-- | doc/src/sgml/ref/pgarchivecleanup.sgml | 4 | ||||
| -rw-r--r-- | doc/src/sgml/ref/pgupgrade.sgml | 2 | ||||
| -rw-r--r-- | doc/src/sgml/release-10.sgml | 2 | ||||
| -rw-r--r-- | doc/src/sgml/release-9.1.sgml | 5 | ||||
| -rw-r--r-- | doc/src/sgml/release-9.4.sgml | 15 | ||||
| -rw-r--r-- | doc/src/sgml/release-9.5.sgml | 11 | ||||
| -rw-r--r-- | doc/src/sgml/release.sgml | 3 |
17 files changed, 574 insertions, 592 deletions
diff --git a/doc/src/sgml/backup.sgml b/doc/src/sgml/backup.sgml index 3fa5efdd789..a73fd4d044f 100644 --- a/doc/src/sgml/backup.sgml +++ b/doc/src/sgml/backup.sgml @@ -1220,8 +1220,11 @@ SELECT pg_stop_backup(); </listitem> <listitem> <para> - Create a recovery command file <filename>recovery.conf</filename> in the cluster - data directory (see <xref linkend="recovery-config"/>). You might + Set recovery configuration settings in + <filename>postgresql.conf</filename> (see <xref + linkend="runtime-config-wal-archive-recovery"/>) and create a file + <filename>recovery.signal</filename> in the cluster + data directory. You might also want to temporarily modify <filename>pg_hba.conf</filename> to prevent ordinary users from connecting until you are sure the recovery was successful. </para> @@ -1232,8 +1235,8 @@ SELECT pg_stop_backup(); proceed to read through the archived WAL files it needs. Should the recovery be terminated because of an external error, the server can simply be restarted and it will continue recovery. Upon completion - of the recovery process, the server will rename - <filename>recovery.conf</filename> to <filename>recovery.done</filename> (to prevent + of the recovery process, the server will remove + <filename>recovery.signal</filename> (to prevent accidentally re-entering recovery mode later) and then commence normal database operations. </para> @@ -1249,12 +1252,9 @@ SELECT pg_stop_backup(); </para> <para> - The key part of all this is to set up a recovery configuration file that + The key part of all this is to set up a recovery configuration that describes how you want to recover and how far the recovery should - run. You can use <filename>recovery.conf.sample</filename> (normally - located in the installation's <filename>share/</filename> directory) as a - prototype. The one thing that you absolutely must specify in - <filename>recovery.conf</filename> is the <varname>restore_command</varname>, + run. The one thing that you absolutely must specify is the <varname>restore_command</varname>, which tells <productname>PostgreSQL</productname> how to retrieve archived WAL file segments. Like the <varname>archive_command</varname>, this is a shell command string. It can contain <literal>%f</literal>, which is @@ -1316,7 +1316,7 @@ restore_command = 'cp /mnt/server/archivedir/%f %p' <para> If you want to recover to some previous point in time (say, right before the junior DBA dropped your main transaction table), just specify the - required <link linkend="recovery-target-settings">stopping point</link> in <filename>recovery.conf</filename>. You can specify + required <link linkend="runtime-config-wal-recovery-target">stopping point</link>. You can specify the stop point, known as the <quote>recovery target</quote>, either by date/time, named restore point or by completion of a specific transaction ID. As of this writing only the date/time and named restore point options @@ -1414,7 +1414,7 @@ restore_command = 'cp /mnt/server/archivedir/%f %p' that was current when the base backup was taken. If you wish to recover into some child timeline (that is, you want to return to some state that was itself generated after a recovery attempt), you need to specify the - target timeline ID in <filename>recovery.conf</filename>. You cannot recover into + target timeline ID in <xref linkend="guc-recovery-target-timeline"/>. You cannot recover into timelines that branched off earlier than the base backup. </para> </sect2> diff --git a/doc/src/sgml/config.sgml b/doc/src/sgml/config.sgml index d1dab355590..db1a2d4e746 100644 --- a/doc/src/sgml/config.sgml +++ b/doc/src/sgml/config.sgml @@ -3044,6 +3044,377 @@ include_dir 'conf.d' </variablelist> </sect2> + <sect2 id="runtime-config-wal-archive-recovery"> + + <title>Archive Recovery</title> + + <indexterm> + <primary>configuration</primary> + <secondary>of recovery</secondary> + <tertiary>of a standby server</tertiary> + </indexterm> + + <para> + This section describes the settings that apply only for the duration of + the recovery. They must be reset for any subsequent recovery you wish to + perform. They can only be set at server start and cannot be changed once + recovery has begun. + </para> + + <para> + <quote>Recovery</quote> covers using the server as a standby or for + executing a targeted recovery. Typically, standby mode would be used to + provide high availability and/or read scalability, whereas a targeted + recovery is used to recover from data loss. + </para> + + <para> + To start the server in standby mode create file called + <filename>standby.signal</filename><indexterm><primary>standby.signal</primary></indexterm> + in the data directory. The server will enter recovery and will not stop + recovery when the end of archived WAL is reached, but will keep trying to + continue recovery by connecting to the sending server as specified by the + <varname>primary_conninfo</varname> setting and/or by fetching new WAL + segments using <varname>restore_command</varname>. In this mode, you may + use parameters in both <xref + linkend="runtime-config-wal-archive-recovery"/> and <xref + linkend="runtime-config-replication-standby"/> sections. Parameters from + <xref linkend="runtime-config-wal-recovery-target"/> will not be used. + </para> + + <para> + To start the server in targeted recovery create a file called + <filename>recovery.signal</filename><indexterm><primary>recovery.signal</primary></indexterm> + in the data directory. If both <filename>standby.signal</filename> and + <filename>recovery.signal</filename> files are created, standby mode + takes precedence. Targeted recovery mode will end when end of archived + WAL is reached, or when <varname>recovery_target</varname> is reached. + In this mode you may use parameters from both <xref + linkend="runtime-config-wal-archive-recovery"/> and <xref + linkend="runtime-config-wal-recovery-target"/> sections. Parameters from <xref + linkend="runtime-config-replication-standby"/> will not be used. + </para> + + <variablelist> + <varlistentry id="guc-restore-command" xreflabel="restore_command"> + <term><varname>restore_command</varname> (<type>string</type>) + <indexterm> + <primary><varname>restore_command</varname> configuration 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</literal> in the string is + replaced by the name of the file to retrieve from the archive, + and any <literal>%p</literal> 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</literal> 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</literal> is typically only + used by warm-standby configurations + (see <xref linkend="warm-standby"/>). + Write <literal>%%</literal> to embed an actual <literal>%</literal> character. + </para> + + <para> + It is important for the command to return a zero exit status + only if it succeeds. The command <emphasis>will</emphasis> 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="guc-archive-cleanup-command" xreflabel="archive_cleanup_command"> + <term><varname>archive_cleanup_command</varname> (<type>string</type>) + <indexterm> + <primary><varname>archive_cleanup_command</varname> configuration 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</varname> is to provide a mechanism for + cleaning up old archived WAL files that are no longer needed by the + standby server. + Any <literal>%r</literal> is replaced by the name of the file containing the + last valid restart point. + That is the earliest file that must be <emphasis>kept</emphasis> to allow a + restore to be restartable, and so all files earlier than <literal>%r</literal> + 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</varname> 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</varname> would typically be used in a + warm-standby configuration (see <xref linkend="warm-standby"/>). + Write <literal>%%</literal> to embed an actual <literal>%</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="guc-recovery-end-command" xreflabel="recovery_end_command"> + <term><varname>recovery_end_command</varname> (<type>string</type>) + <indexterm> + <primary><varname>recovery_end_command</varname> configuration 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</varname> is to provide a mechanism for cleanup + following replication or recovery. + Any <literal>%r</literal> is replaced by the name of the file containing the + last valid restart point, like in <xref linkend="guc-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> + + </sect2> + + <sect2 id="runtime-config-wal-recovery-target"> + + <title>Recovery Target</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>, + <varname>recovery_target_lsn</varname>, <varname>recovery_target_name</varname>, + <varname>recovery_target_time</varname>, or <varname>recovery_target_xid</varname> + can be used; if more than one of these is specified in the configuration + file, the last entry will be used. + These parameters can only be set at server start. + </para> + + <variablelist> + <varlistentry id="guc-recovery-target" xreflabel="recovery_target"> + <term><varname>recovery_target</varname><literal> = 'immediate'</literal> + <indexterm> + <primary><varname>recovery_target</varname> configuration 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'</literal> + is currently the only allowed value. + </para> + </listitem> + </varlistentry> + + <varlistentry id="guc-recovery-target-name" xreflabel="recovery_target_name"> + <term><varname>recovery_target_name</varname> (<type>string</type>) + <indexterm> + <primary><varname>recovery_target_name</varname> configuration parameter</primary> + </indexterm> + </term> + <listitem> + <para> + This parameter specifies the named restore point (created with + <function>pg_create_restore_point()</function>) to which recovery will proceed. + </para> + </listitem> + </varlistentry> + + <varlistentry id="guc-recovery-target-time" xreflabel="recovery_target_time"> + <term><varname>recovery_target_time</varname> (<type>timestamp</type>) + <indexterm> + <primary><varname>recovery_target_time</varname> configuration 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="guc-recovery-target-inclusive"/>. + </para> + </listitem> + </varlistentry> + + <varlistentry id="guc-recovery-target-xid" xreflabel="recovery_target_xid"> + <term><varname>recovery_target_xid</varname> (<type>string</type>) + <indexterm> + <primary><varname>recovery_target_xid</varname> configuration 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="guc-recovery-target-inclusive"/>. + </para> + </listitem> + </varlistentry> + + <varlistentry id="guc-recovery-target-lsn" xreflabel="recovery_target_lsn"> + <term><varname>recovery_target_lsn</varname> (<type>pg_lsn</type>) + <indexterm> + <primary><varname>recovery_target_lsn</varname> configuration parameter</primary> + </indexterm> + </term> + <listitem> + <para> + This parameter specifies the LSN of the write-ahead log location up + to which recovery will proceed. The precise stopping point is also + influenced by <xref linkend="guc-recovery-target-inclusive"/>. This + parameter is parsed using the system data type + <link linkend="datatype-pg-lsn"><type>pg_lsn</type></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="guc-recovery-target-inclusive" + xreflabel="recovery_target_inclusive"> + <term><varname>recovery_target_inclusive</varname> (<type>boolean</type>) + <indexterm> + <primary><varname>recovery_target_inclusive</varname> configuration 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 <xref linkend="guc-recovery-target-lsn"/>, + <xref linkend="guc-recovery-target-time"/>, or + <xref linkend="guc-recovery-target-xid"/> is specified. + This setting controls whether transactions + having exactly the target WAL location (LSN), commit time, or transaction ID, respectively, will + be included in the recovery. Default is <literal>true</literal>. + </para> + </listitem> + </varlistentry> + + <varlistentry id="guc-recovery-target-timeline" + xreflabel="recovery_target_timeline"> + <term><varname>recovery_target_timeline</varname> (<type>string</type>) + <indexterm> + <primary><varname>recovery_target_timeline</varname> configuration 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</literal> 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="guc-recovery-target-action" + xreflabel="recovery_target_action"> + <term><varname>recovery_target_action</varname> (<type>enum</type>) + <indexterm> + <primary><varname>recovery_target_action</varname> configuration parameter</primary> + </indexterm> + </term> + <listitem> + <para> + Specifies what action the server should take once the recovery target is + reached. The default is <literal>pause</literal>, which means recovery will + be paused. <literal>promote</literal> means the recovery process will finish + and the server will start to accept connections. + Finally <literal>shutdown</literal> will stop the server after reaching the + recovery target. + </para> + <para> + The intended use of the <literal>pause</literal> 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_wal_replay_resume()</function> (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</literal> 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.signal</filename> will not be + removed when <varname>recovery_target_action</varname> is set to <literal>shutdown</literal>, + any subsequent start will end with immediate shutdown unless the + configuration is changed or the <filename>recovery.signal</filename> + 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</literal> will act the same as <literal>shutdown</literal>. + </para> + </listitem> + </varlistentry> + + </variablelist> + </sect2> + </sect1> <sect1 id="runtime-config-replication"> @@ -3247,11 +3618,11 @@ include_dir 'conf.d' <varname>application_name</varname> setting of the standby, as set in the standby's connection information. In case of a physical replication standby, this should be set in the <varname>primary_conninfo</varname> - setting in <filename>recovery.conf</filename>; the default - is <literal>walreceiver</literal>. For logical replication, this can - be set in the connection information of the subscription, and it - defaults to the subscription name. For other replication stream - consumers, consult their documentation. + setting; the default is <literal>walreceiver</literal>. + For logical replication, this can be set in the connection + information of the subscription, and it defaults to the + subscription name. For other replication stream consumers, + consult their documentation. </para> <para> This parameter specifies a list of standby servers using @@ -3394,6 +3765,79 @@ ANY <replaceable class="parameter">num_sync</replaceable> ( <replaceable class=" <variablelist> + <varlistentry id="guc-primary-conninfo" xreflabel="primary_conninfo"> + <term><varname>primary_conninfo</varname> (<type>string</type>) + <indexterm> + <primary><varname>primary_conninfo</varname> configuration parameter</primary> + </indexterm> + </term> + <listitem> + <para> + Specifies a connection string to be used for the standby server + to connect with a sending server. 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 sending 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 sending server (see + <xref linkend="streaming-replication-authentication"/>). + A password needs to be provided too, if the sender demands password + authentication. It can be provided in the + <varname>primary_conninfo</varname> string, or in a separate + <filename>~/.pgpass</filename> file on the standby server (use + <literal>replication</literal> as the database name). + Do not specify a database name in the + <varname>primary_conninfo</varname> string. + </para> + <para> + This parameter can only be set at server start. + This setting has no effect if the server is not in standby mode. + </para> + </listitem> + </varlistentry> + <varlistentry id="guc-primary-slot-name" xreflabel="primary_slot_name"> + <term><varname>primary_slot_name</varname> (<type>string</type>) + <indexterm> + <primary><varname>primary_slot_name</varname> configuration parameter</primary> + </indexterm> + </term> + <listitem> + <para> + Optionally specifies an existing replication slot to be used when + connecting to the sending server via streaming replication to control + resource removal on the upstream node + (see <xref linkend="streaming-replication-slots"/>). + This parameter can only be set at server start. + This setting has no effect if <varname>primary_conninfo</varname> is not + set. + </para> + </listitem> + </varlistentry> + + <varlistentry id="guc-promote-trigger-file" xreflabel="promote_trigger_file"> + <term><varname>promote_trigger_file</varname> (<type>string</type>) + <indexterm> + <primary><varname>promote_trigger_file</varname> configuration 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</command> or calling + <function>pg_promote</function>. + This parameter can only be set at server start. + </para> + </listitem> + </varlistentry> + <varlistentry id="guc-hot-standby" xreflabel="hot_standby"> <term><varname>hot_standby</varname> (<type>boolean</type>) <indexterm> @@ -3587,6 +4031,67 @@ ANY <replaceable class="parameter">num_sync</replaceable> ( <replaceable class=" </listitem> </varlistentry> + <varlistentry id="guc-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</varname> configuration parameter</primary> + </indexterm> + </term> + <listitem> + <para> + By default, a standby server restores WAL records from the + sending server 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</varname> 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> + <para> + This parameter can only be set at server start. + </para> + </listitem> + </varlistentry> + </variablelist> </sect2> diff --git a/doc/src/sgml/filelist.sgml b/doc/src/sgml/filelist.sgml index 48ac14a8380..0a10df64022 100644 --- a/doc/src/sgml/filelist.sgml +++ b/doc/src/sgml/filelist.sgml @@ -42,7 +42,6 @@ <!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/func.sgml b/doc/src/sgml/func.sgml index d7302617423..09c77db0455 100644 --- a/doc/src/sgml/func.sgml +++ b/doc/src/sgml/func.sgml @@ -19094,7 +19094,7 @@ postgres=# select pg_start_backup('label_goes_here'); <function>pg_create_restore_point</function> creates a named write-ahead log record that can be used as recovery target, and returns the corresponding write-ahead log location. The given name can then be used with - <xref linkend="recovery-target-name"/> to specify the point up to which + <xref linkend="guc-recovery-target-name"/> to specify the point up to which recovery will proceed. Avoid creating multiple restore points with the same name, since recovery will stop at the first one whose name matches the recovery target. diff --git a/doc/src/sgml/high-availability.sgml b/doc/src/sgml/high-availability.sgml index faf8e718549..d8fd195da09 100644 --- a/doc/src/sgml/high-availability.sgml +++ b/doc/src/sgml/high-availability.sgml @@ -618,7 +618,7 @@ protocol to make nodes agree on a serializable transactional order. <para> In standby mode, the server continuously applies WAL received from the master server. The standby server can read WAL from a WAL archive - (see <xref linkend="restore-command"/>) or directly from the master + (see <xref linkend="guc-restore-command"/>) or directly from the master over a TCP connection (streaming replication). The standby server will also attempt to restore any WAL found in the standby cluster's <filename>pg_wal</filename> directory. That typically happens after a server @@ -645,7 +645,7 @@ protocol to make nodes agree on a serializable transactional order. <para> Standby mode is exited and the server switches to normal operation when <command>pg_ctl promote</command> is run or a trigger file is found - (<varname>trigger_file</varname>). Before failover, + (<varname>promote_trigger_file</varname>). Before failover, any WAL immediately available in the archive or in <filename>pg_wal</filename> will be restored, but no attempt is made to connect to the master. </para> @@ -686,10 +686,9 @@ protocol to make nodes agree on a serializable transactional order. <para> To set up the standby server, restore the base backup taken from primary - server (see <xref linkend="backup-pitr-recovery"/>). Create a recovery - command file <filename>recovery.conf</filename> in the standby's cluster data - directory, and turn on <varname>standby_mode</varname>. Set - <varname>restore_command</varname> to a simple command to copy files from + server (see <xref linkend="backup-pitr-recovery"/>). Create a file + <filename>standby.signal</filename> in the standby's cluster data + directory. Set <xref linkend="guc-restore-command"/> to a simple command to copy files from the WAL archive. If you plan to have multiple standby servers for high availability purposes, set <varname>recovery_target_timeline</varname> to <literal>latest</literal>, to make the standby server follow the timeline change @@ -699,7 +698,7 @@ protocol to make nodes agree on a serializable transactional order. <note> <para> Do not use pg_standby or similar tools with the built-in standby mode - described here. <varname>restore_command</varname> should return immediately + described here. <xref linkend="guc-restore-command"/> should return immediately if the file does not exist; the server will retry the command again if necessary. See <xref linkend="log-shipping-alternative"/> for using tools like pg_standby. @@ -708,11 +707,11 @@ protocol to make nodes agree on a serializable transactional order. <para> If you want to use streaming replication, fill in - <varname>primary_conninfo</varname> with a libpq connection string, including + <xref linkend="guc-primary-conninfo"/> with a libpq connection string, including the host name (or IP address) and any additional details needed to connect to the primary server. If the primary needs a password for authentication, the password needs to be specified in - <varname>primary_conninfo</varname> as well. + <xref linkend="guc-primary-conninfo"/> as well. </para> <para> @@ -724,7 +723,7 @@ protocol to make nodes agree on a serializable transactional order. <para> If you're using a WAL archive, its size can be minimized using the <xref - linkend="archive-cleanup-command"/> parameter to remove files that are no + linkend="guc-archive-cleanup-command"/> parameter to remove files that are no longer required by the standby server. The <application>pg_archivecleanup</application> utility is designed specifically to be used with <varname>archive_cleanup_command</varname> in typical single-standby @@ -735,9 +734,8 @@ protocol to make nodes agree on a serializable transactional order. </para> <para> - A simple example of a <filename>recovery.conf</filename> is: + A simple example of configuration is: <programlisting> -standby_mode = 'on' primary_conninfo = 'host=192.168.1.50 port=5432 user=foo password=foopass options=''-c wal_sender_timeout=5000''' restore_command = 'cp /path/to/archive/%f %p' archive_cleanup_command = 'pg_archivecleanup /path/to/archive %r' @@ -793,8 +791,8 @@ archive_cleanup_command = 'pg_archivecleanup /path/to/archive %r' To use streaming replication, set up a file-based log-shipping standby server as described in <xref linkend="warm-standby"/>. The step that turns a file-based log-shipping standby into streaming replication - standby is setting <varname>primary_conninfo</varname> setting in the - <filename>recovery.conf</filename> file to point to the primary server. Set + standby is setting the <varname>primary_conninfo</varname> setting + to point to the primary server. Set <xref linkend="guc-listen-addresses"/> and authentication options (see <filename>pg_hba.conf</filename>) on the primary so that the standby server can connect to the <literal>replication</literal> pseudo-database on the primary @@ -854,14 +852,14 @@ host replication foo 192.168.1.100/32 md5 </para> <para> The host name and port number of the primary, connection user name, - and password are specified in the <filename>recovery.conf</filename> file. + and password are specified in the <xref linkend="guc-primary-conninfo"/>. The password can also be set in the <filename>~/.pgpass</filename> file on the standby (specify <literal>replication</literal> in the <replaceable>database</replaceable> field). For example, if the primary is running on host IP <literal>192.168.1.50</literal>, port <literal>5432</literal>, the account name for replication is <literal>foo</literal>, and the password is <literal>foopass</literal>, the administrator - can add the following line to the <filename>recovery.conf</filename> file on the + can add the following line to the <filename>postgresql.conf</filename> file on the standby: <programlisting> @@ -973,10 +971,8 @@ postgres=# SELECT slot_name, slot_type, active FROM pg_replication_slots; (1 row) </programlisting> To configure the standby to use this slot, <varname>primary_slot_name</varname> - should be configured in the standby's <filename>recovery.conf</filename>. - Here is a simple example: + should be configured on the standby. Here is a simple example: <programlisting> -standby_mode = 'on' primary_conninfo = 'host=192.168.1.50 port=5432 user=foo password=foopass' primary_slot_name = 'node_a_slot' </programlisting> @@ -1474,11 +1470,10 @@ synchronous_standby_names = 'ANY 2 (s1, s2, s3)' To trigger failover of a log-shipping standby server, run <command>pg_ctl promote</command>, call <function>pg_promote</function>, or create a trigger file with the file name and path specified by the - <varname>trigger_file</varname> setting in - <filename>recovery.conf</filename>. If you're planning to use + <varname>promote_trigger_file</varname>. If you're planning to use <command>pg_ctl promote</command> or to call <function>pg_promote</function> to fail over, - <varname>trigger_file</varname> is not required. If you're + <varname>promote_trigger_file</varname> is not required. If you're setting up the reporting servers that are only used to offload read-only queries from the primary, not for high availability purposes, you don't need to promote it. @@ -1491,11 +1486,8 @@ synchronous_standby_names = 'ANY 2 (s1, s2, s3)' <para> An alternative to the built-in standby mode described in the previous sections is to use a <varname>restore_command</varname> that polls the archive location. - This was the only option available in versions 8.4 and below. In this - setup, set <varname>standby_mode</varname> off, because you are implementing - the polling required for standby operation yourself. See the - <xref linkend="pgstandby"/> module for a reference - implementation of this. + This was the only option available in versions 8.4 and below. See the + <xref linkend="pgstandby"/> module for a reference implementation of this. </para> <para> @@ -1522,8 +1514,7 @@ synchronous_standby_names = 'ANY 2 (s1, s2, s3)' The magic that makes the two loosely coupled servers work together is simply a <varname>restore_command</varname> used on the standby that, when asked for the next WAL file, waits for it to become available from - the primary. The <varname>restore_command</varname> is specified in the - <filename>recovery.conf</filename> file on the standby server. Normal recovery + the primary. Normal recovery processing would request a file from the WAL archive, reporting failure if the file was unavailable. For standby processing it is normal for the next WAL file to be unavailable, so the standby must wait for @@ -1611,9 +1602,8 @@ if (!triggered) <listitem> <para> Begin recovery on the standby server from the local WAL - archive, using a <filename>recovery.conf</filename> that specifies a - <varname>restore_command</varname> that waits as described - previously (see <xref linkend="backup-pitr-recovery"/>). + archive, using <varname>restore_command</varname> that waits + as described previously (see <xref linkend="backup-pitr-recovery"/>). </para> </listitem> </orderedlist> @@ -2108,7 +2098,7 @@ if (!triggered) <para> If <varname>hot_standby</varname> is <literal>on</literal> in <filename>postgresql.conf</filename> - (the default value) and there is a <filename>recovery.conf</filename> + (the default value) and there is a <filename>standby.signal</filename> file present, the server will run in Hot Standby mode. However, it may take some time for Hot Standby connections to be allowed, because the server will not accept connections until it has completed diff --git a/doc/src/sgml/pgstandby.sgml b/doc/src/sgml/pgstandby.sgml index 2cc58fe3567..d8aded43840 100644 --- a/doc/src/sgml/pgstandby.sgml +++ b/doc/src/sgml/pgstandby.sgml @@ -47,7 +47,7 @@ <para> To configure a standby server to use <application>pg_standby</application>, put this into its - <filename>recovery.conf</filename> configuration file: + <filename>postgresql.conf</filename> configuration file: <programlisting> restore_command = 'pg_standby <replaceable>archiveDir</replaceable> %f %p %r' </programlisting> diff --git a/doc/src/sgml/postgres.sgml b/doc/src/sgml/postgres.sgml index 0070603fc36..142799316aa 100644 --- a/doc/src/sgml/postgres.sgml +++ b/doc/src/sgml/postgres.sgml @@ -158,7 +158,6 @@ &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 deleted file mode 100644 index a2bdffda94d..00000000000 --- a/doc/src/sgml/recovery-config.sgml +++ /dev/null @@ -1,510 +0,0 @@ -<!-- 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</filename><indexterm><primary>recovery.conf</primary></indexterm> - 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</filename> are specified in the format - <literal>name = 'value'</literal>. 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>''</literal>). - </para> - - <para> - A sample file, <filename>share/recovery.conf.sample</filename>, - is provided in the installation's <filename>share/</filename> 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</varname> 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</literal> in the string is - replaced by the name of the file to retrieve from the archive, - and any <literal>%p</literal> 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</literal> 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</literal> is typically only - used by warm-standby configurations - (see <xref linkend="warm-standby"/>). - Write <literal>%%</literal> to embed an actual <literal>%</literal> character. - </para> - - <para> - It is important for the command to return a zero exit status - only if it succeeds. The command <emphasis>will</emphasis> 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</varname> 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</varname> is to provide a mechanism for - cleaning up old archived WAL files that are no longer needed by the - standby server. - Any <literal>%r</literal> is replaced by the name of the file containing the - last valid restart point. - That is the earliest file that must be <emphasis>kept</emphasis> to allow a - restore to be restartable, and so all files earlier than <literal>%r</literal> - 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</varname> 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</varname> would typically be used in a - warm-standby configuration (see <xref linkend="warm-standby"/>). - Write <literal>%%</literal> to embed an actual <literal>%</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</varname> 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</varname> is to provide a mechanism for cleanup - following replication or recovery. - Any <literal>%r</literal> 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>, - <varname>recovery_target_lsn</varname>, <varname>recovery_target_name</varname>, - <varname>recovery_target_time</varname>, or <varname>recovery_target_xid</varname> - 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</varname> 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'</literal> - 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</varname> recovery parameter</primary> - </indexterm> - </term> - <listitem> - <para> - This parameter specifies the named restore point (created with - <function>pg_create_restore_point()</function>) 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</varname> 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</varname> 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</varname> recovery parameter</primary> - </indexterm> - </term> - <listitem> - <para> - This parameter specifies the LSN of the write-ahead 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</type></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</varname> 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 <xref linkend="recovery-target-lsn"/>, - <xref linkend="recovery-target-time"/>, or - <xref linkend="recovery-target-xid"/> is specified. - This setting controls whether transactions - having exactly the target WAL location (LSN), commit time, or transaction ID, respectively, will - be included in the recovery. Default is <literal>true</literal>. - </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</varname> 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</literal> 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</varname> 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</literal>, which means recovery will - be paused. <literal>promote</literal> means the recovery process will finish - and the server will start to accept connections. - Finally <literal>shutdown</literal> will stop the server after reaching the - recovery target. - </para> - <para> - The intended use of the <literal>pause</literal> 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_wal_replay_resume()</function> (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</literal> 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</filename> will not be renamed when - <varname>recovery_target_action</varname> is set to <literal>shutdown</literal>, - any subsequent start will end with immediate shutdown unless the - configuration is changed or the <filename>recovery.conf</filename> 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</literal> will act the same as <literal>shutdown</literal>. - </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</varname> recovery parameter</primary> - </indexterm> - </term> - <listitem> - <para> - Specifies whether to start the <productname>PostgreSQL</productname> server as - a standby. If this parameter is <literal>on</literal>, 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</varname> - and/or by connecting to the primary server as specified by the - <varname>primary_conninfo</varname> setting. - </para> - </listitem> - </varlistentry> - <varlistentry id="primary-conninfo" xreflabel="primary_conninfo"> - <term><varname>primary_conninfo</varname> (<type>string</type>) - <indexterm> - <primary><varname>primary_conninfo</varname> 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</filename> file on the standby server (use - <literal>replication</literal> 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</varname> is <literal>off</literal>. - </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</varname> 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</varname> 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</varname> 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</command> or calling - <function>pg_promote</function>. - This setting has no effect if <varname>standby_mode</varname> is <literal>off</literal>. - </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</varname> 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</varname> 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> diff --git a/doc/src/sgml/ref/pg_basebackup.sgml b/doc/src/sgml/ref/pg_basebackup.sgml index c9f6ce4bb33..57dc83b620b 100644 --- a/doc/src/sgml/ref/pg_basebackup.sgml +++ b/doc/src/sgml/ref/pg_basebackup.sgml @@ -214,10 +214,11 @@ PostgreSQL documentation <listitem> <para> - Write a minimal <filename>recovery.conf</filename> in the output + Create <filename>standby.signal</filename> and append connection settings + to <filename>postgresql.auto.conf</filename> in the output directory (or into the base archive file when using tar format) to ease setting up a standby server. - The <filename>recovery.conf</filename> file will record the connection + The <filename>postgresql.auto.conf</filename> file will record the connection settings and, if specified, the replication slot that <application>pg_basebackup</application> is using, so that the streaming replication will use the same settings later on. @@ -470,7 +471,7 @@ PostgreSQL documentation replication slot. If the base backup is intended to be used as a streaming replication standby using replication slots, it should then use the same replication slot name - in <filename>recovery.conf</filename>. That way, it is ensured that + in <xref linkend="guc-primary-slot-name"/>. That way, it is ensured that the server does not remove any necessary WAL data in the time between the end of the base backup and the start of streaming replication. </para> diff --git a/doc/src/sgml/ref/pg_rewind.sgml b/doc/src/sgml/ref/pg_rewind.sgml index e2662bbf819..53a64ee29ef 100644 --- a/doc/src/sgml/ref/pg_rewind.sgml +++ b/doc/src/sgml/ref/pg_rewind.sgml @@ -69,7 +69,8 @@ PostgreSQL documentation target cluster ran for a long time after the divergence, the old WAL files might no longer be present. In that case, they can be manually copied from the WAL archive to the <filename>pg_wal</filename> directory, or - fetched on startup by configuring <filename>recovery.conf</filename>. The use of + fetched on startup by configuring <xref linkend="guc-primary-conninfo"/> or + <xref linkend="guc-restore-command"/>. The use of <application>pg_rewind</application> is not limited to failover, e.g. a standby server can be promoted, run some write transactions, and then rewinded to become a standby again. @@ -83,8 +84,9 @@ PostgreSQL documentation <application>pg_rewind</application> was run, and therefore could not be copied by the <application>pg_rewind</application> session, it must be made available when the target server is started. This can be done by creating a - <filename>recovery.conf</filename> file in the target data directory with a - suitable <varname>restore_command</varname>. + <filename>recovery.signal</filename> file in the target data directory + and configuring suitable <xref linkend="guc-restore-command"/> + in <filename>postgresql.conf</filename>. </para> <para> diff --git a/doc/src/sgml/ref/pgarchivecleanup.sgml b/doc/src/sgml/ref/pgarchivecleanup.sgml index 4117a4392c1..a3d3538b28a 100644 --- a/doc/src/sgml/ref/pgarchivecleanup.sgml +++ b/doc/src/sgml/ref/pgarchivecleanup.sgml @@ -39,7 +39,7 @@ <para> To configure a standby server to use <application>pg_archivecleanup</application>, put this into its - <filename>recovery.conf</filename> configuration file: + <filename>postgresql.conf</filename> configuration file: <programlisting> archive_cleanup_command = 'pg_archivecleanup <replaceable>archivelocation</replaceable> %r' </programlisting> @@ -47,7 +47,7 @@ archive_cleanup_command = 'pg_archivecleanup <replaceable>archivelocation</repla files should be removed. </para> <para> - When used within <xref linkend="archive-cleanup-command"/>, all WAL files + When used within <xref linkend="guc-archive-cleanup-command"/>, all WAL files logically preceding the value of the <literal>%r</literal> argument will be removed from <replaceable>archivelocation</replaceable>. This minimizes the number of files that need to be retained, while preserving crash-restart capability. Use of diff --git a/doc/src/sgml/ref/pgupgrade.sgml b/doc/src/sgml/ref/pgupgrade.sgml index 2d722b2e792..978fa252e40 100644 --- a/doc/src/sgml/ref/pgupgrade.sgml +++ b/doc/src/sgml/ref/pgupgrade.sgml @@ -506,7 +506,7 @@ pg_upgrade.exe <para> Save any configuration files from the old standbys' configuration directories you need to keep, e.g. <filename>postgresql.conf</filename>, - <literal>recovery.conf</literal>, because these will be overwritten or + <literal>pg_hba.conf</literal>, because these will be overwritten or removed in the next step. </para> </step> diff --git a/doc/src/sgml/release-10.sgml b/doc/src/sgml/release-10.sgml index de7779f622b..aacdd360e05 100644 --- a/doc/src/sgml/release-10.sgml +++ b/doc/src/sgml/release-10.sgml @@ -7303,7 +7303,7 @@ This was disabled in the PG 9.6 branch so there is no commit here. <para> Allow specification of the recovery stopping point by Log Sequence Number (<acronym>LSN</acronym>) in - <link linkend="recovery-config"><filename>recovery.conf</filename></link> + <filename>recovery.conf</filename> (Michael Paquier) </para> diff --git a/doc/src/sgml/release-9.1.sgml b/doc/src/sgml/release-9.1.sgml index 3407d8ad739..217b340bc3c 100644 --- a/doc/src/sgml/release-9.1.sgml +++ b/doc/src/sgml/release-9.1.sgml @@ -9811,7 +9811,7 @@ Branch: REL9_0_STABLE [9d6af7367] 2015-08-15 11:02:34 -0400 <para> These named restore points can be specified as recovery targets using the new <filename>recovery.conf</filename> setting - <link linkend="recovery-target-name"><varname>recovery_target_name</varname></link>. + <varname>recovery_target_name</varname>. </para> </listitem> @@ -9843,8 +9843,7 @@ Branch: REL9_0_STABLE [9d6af7367] 2015-08-15 11:02:34 -0400 <listitem> <para> - Allow <link - linkend="recovery-config"><filename>recovery.conf</filename></link> + Allow <filename>recovery.conf</filename> to use the same quoting behavior as <filename>postgresql.conf</filename> (Dimitri Fontaine) </para> diff --git a/doc/src/sgml/release-9.4.sgml b/doc/src/sgml/release-9.4.sgml index 50442e98b4e..9851d96d42f 100644 --- a/doc/src/sgml/release-9.4.sgml +++ b/doc/src/sgml/release-9.4.sgml @@ -5350,7 +5350,7 @@ Branch: REL9_1_STABLE [de887cc8a] 2016-05-25 19:39:49 -0400 <listitem> <para> - Ignore <xref linkend="recovery-min-apply-delay"/> parameter until + Ignore <varname>recovery_min_apply_delay</varname> parameter until recovery has reached a consistent state (Michael Paquier) </para> @@ -10869,8 +10869,8 @@ Branch: REL9_4_STABLE [c2b06ab17] 2015-01-30 22:45:58 -0500 <listitem> <para> - Use the last specified <link linkend="recovery-target-settings">recovery - target parameter</link> if multiple target parameters are specified + Use the last specified recovery + target parameter if multiple target parameters are specified (Heikki Linnakangas) </para> @@ -10889,7 +10889,7 @@ Branch: REL9_4_STABLE [c2b06ab17] 2015-01-30 22:45:58 -0500 <para> User commands that did their own quote preservation might need adjustment. This is likely to be an issue for commands used in - <xref linkend="guc-archive-command"/>, <xref linkend="restore-command"/>, + <xref linkend="guc-archive-command"/>, <xref linkend="guc-restore-command"/>, and <link linkend="sql-copy"><command>COPY TO/FROM PROGRAM</command></link>. </para> </listitem> @@ -11510,7 +11510,7 @@ Branch: REL9_4_STABLE [c2b06ab17] 2015-01-30 22:45:58 -0500 <listitem> <para> - Add recovery parameter <xref linkend="recovery-min-apply-delay"/> + Add recovery parameter <varname>recovery_min_apply_delay</varname> to delay replication (Robert Haas, Fabrízio de Royes Mello, Simon Riggs) </para> @@ -11523,7 +11523,7 @@ Branch: REL9_4_STABLE [c2b06ab17] 2015-01-30 22:45:58 -0500 <listitem> <para> - Add <xref linkend="recovery-target"/> + Add <varname>recovery_target</varname> option <option>immediate</option> to stop <link linkend="wal"><acronym>WAL</acronym></link> recovery as soon as a consistent state is reached (MauMau, Heikki Linnakangas) @@ -11559,8 +11559,7 @@ Branch: REL9_4_STABLE [c2b06ab17] 2015-01-30 22:45:58 -0500 <listitem> <para> - Report failure return codes from <link - linkend="archive-recovery-settings">external recovery commands</link> + Report failure return codes from external recovery commands (Peter Eisentraut) </para> </listitem> diff --git a/doc/src/sgml/release-9.5.sgml b/doc/src/sgml/release-9.5.sgml index ccd8eee3e37..00d5619a0a5 100644 --- a/doc/src/sgml/release-9.5.sgml +++ b/doc/src/sgml/release-9.5.sgml @@ -7305,7 +7305,7 @@ Branch: REL9_4_STABLE [a9613ee69] 2016-03-06 02:43:26 +0900 <listitem> <para> - Ignore <xref linkend="recovery-min-apply-delay"/> parameter until + Ignore <varname>recovery_min_apply_delay</varname> parameter until recovery has reached a consistent state (Michael Paquier) </para> @@ -9096,9 +9096,8 @@ Add GUC and storage parameter to set the maximum size of GIN pending list. 2015-03-15 [51c11a7] Andres..: Remove pause_at_recovery_target recovery.conf s.. --> <para> - Add <link linkend="recovery-config"><filename>recovery.conf</filename></link> - parameter <link - linkend="recovery-target-action"><varname>recovery_target_action</varname></link> + Add <filename>recovery.conf</filename> + parameter <varname>recovery_target_action</varname> to control post-recovery activity (Petr Jelínek) </para> @@ -9199,8 +9198,8 @@ Add GUC and storage parameter to set the maximum size of GIN pending list. 2014-11-25 [b3fc672] Heikki..: Allow using connection URI in primary_conninfo. --> <para> - Allow <filename>recovery.conf</filename>'s <link - linkend="primary-conninfo"><varname>primary_conninfo</varname></link> setting to + Allow <filename>recovery.conf</filename>'s + <varname>primary_conninfo</varname> setting to use connection <acronym>URI</acronym>s, e.g. <literal>postgres://</literal> (Alexander Shulgin) </para> diff --git a/doc/src/sgml/release.sgml b/doc/src/sgml/release.sgml index c4e763a0432..4055adf88f2 100644 --- a/doc/src/sgml/release.sgml +++ b/doc/src/sgml/release.sgml @@ -5,8 +5,7 @@ Typical markup: &<> use & escapes PostgreSQL <productname> -postgresql.conf, pg_hba.conf, - recovery.conf <filename> +postgresql.conf, pg_hba.conf <filename> [A-Z][A-Z_ ]+[A-Z_] <command>, <literal>, <envar>, <acronym> [A-Za-z_][A-Za-z0-9_]+() <function> \-\-?[A-Za-z_]+[-A-Za-z_]* <option> (use backslashes to avoid SGML markup) |