diff options
Diffstat (limited to 'doc/src/sgml/recovery-config.sgml')
| -rw-r--r-- | doc/src/sgml/recovery-config.sgml | 510 |
1 files changed, 0 insertions, 510 deletions
diff --git a/doc/src/sgml/recovery-config.sgml b/doc/src/sgml/recovery-config.sgml deleted file mode 100644 index a2bdffda94..0000000000 --- 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> |