path: root/doc/src/sgml/recovery-config.sgml

<!-- doc/src/sgml/recovery-config.sgml -->

<chapter id="recovery-config">
  <title>Recovery Configuration</title>

  <indexterm>
   <primary>configuration</primary>
   <secondary>of recovery</secondary>
   <tertiary>of a standby server</tertiary>
  </indexterm>

   <para>
    This chapter describes the settings available in the
    <filename>recovery.conf</><indexterm><primary>recovery.conf</></>
    file. They apply only for the duration of the
    recovery.  They must be reset for any subsequent recovery you wish to
    perform.  They cannot be changed once recovery has begun.
   </para>

   <para>
     Settings in <filename>recovery.conf</> are specified in the format
     <literal>name = 'value'</>. One parameter is specified per line.
     Hash marks (<literal>#</literal>) designate the rest of the
     line as a comment.  To embed a single quote in a parameter
     value, write two quotes (<literal>''</>).
   </para>

   <para>
    A sample file, <filename>share/recovery.conf.sample</>,
    is provided in the installation's <filename>share/</> directory.
   </para>

  <sect1 id="archive-recovery-settings">

    <title>Archive Recovery Settings</title>
     <variablelist>

     <varlistentry id="restore-command" xreflabel="restore_command">
      <term><varname>restore_command</varname> (<type>string</type>)
      <indexterm>
        <primary><varname>restore_command</> recovery parameter</primary>
      </indexterm>
      </term>
      <listitem>
       <para>
        The local shell command to execute to retrieve an archived segment of
        the WAL file series. This parameter is required for archive recovery,
        but optional for streaming replication.
        Any <literal>%f</> in the string is
        replaced by the name of the file to retrieve from the archive,
        and any <literal>%p</> is replaced by the copy destination path name
        on the server.
        (The path name is relative to the current working directory,
        i.e., the cluster's data directory.)
        Any <literal>%r</> is replaced by the name of the file containing the
        last valid restart point. That is the earliest file that must be kept
        to allow a restore to be restartable, so this information can be used
        to truncate the archive to just the minimum required to support
        restarting from the current restore. <literal>%r</> is typically only
        used by warm-standby configurations
        (see <xref linkend="warm-standby">).
        Write <literal>%%</> to embed an actual <literal>%</> character.
       </para>

       <para>
        It is important for the command to return a zero exit status
        only if it succeeds.  The command <emphasis>will</> be asked for file
        names that are not present in the archive; it must return nonzero
        when so asked.  Examples:
<programlisting>
restore_command = 'cp /mnt/server/archivedir/%f "%p"'
restore_command = 'copy "C:\\server\\archivedir\\%f" "%p"'  # Windows
</programlisting>
        An exception is that if the command was terminated by a signal (other
        than <systemitem>SIGTERM</systemitem>, which is used as part of a
        database server shutdown) or an error by the shell (such as command
        not found), then recovery will abort and the server will not start up.
       </para>
      </listitem>
     </varlistentry>

     <varlistentry id="archive-cleanup-command" xreflabel="archive_cleanup_command">
      <term><varname>archive_cleanup_command</varname> (<type>string</type>)
      <indexterm>
        <primary><varname>archive_cleanup_command</> recovery parameter</primary>
      </indexterm>
      </term>
      <listitem>
       <para>
        This optional parameter specifies a shell command that will be executed
        at every restartpoint.  The purpose of
        <varname>archive_cleanup_command</> is to provide a mechanism for
        cleaning up old archived WAL files that are no longer needed by the
        standby server.
        Any <literal>%r</> is replaced by the name of the file containing the
        last valid restart point.
        That is the earliest file that must be <emphasis>kept</> to allow a
        restore to be restartable, and so all files earlier than <literal>%r</>
        may be safely removed.
        This information can be used to truncate the archive to just the
        minimum required to support restart from the current restore.
        The <xref linkend="pgarchivecleanup"> module
        is often used in <varname>archive_cleanup_command</> for
        single-standby configurations, for example:
<programlisting>archive_cleanup_command = 'pg_archivecleanup /mnt/server/archivedir %r'</programlisting>
        Note however that if multiple standby servers are restoring from the
        same archive directory, you will need to ensure that you do not delete
        WAL files until they are no longer needed by any of the servers.
        <varname>archive_cleanup_command</> would typically be used in a
        warm-standby configuration (see <xref linkend="warm-standby">).
        Write <literal>%%</> to embed an actual <literal>%</> character in the
        command.
       </para>
       <para>
        If the command returns a nonzero exit status then a warning log
        message will be written.  An exception is that if the command was
        terminated by a signal or an error by the shell (such as command not
        found), a fatal error will be raised.
       </para>
      </listitem>
     </varlistentry>

     <varlistentry id="recovery-end-command" xreflabel="recovery_end_command">
      <term><varname>recovery_end_command</varname> (<type>string</type>)
      <indexterm>
        <primary><varname>recovery_end_command</> recovery parameter</primary>
      </indexterm>
      </term>
      <listitem>
       <para>
        This parameter specifies a shell command that will be executed once only
        at the end of recovery. This parameter is optional. The purpose of the
        <varname>recovery_end_command</> is to provide a mechanism for cleanup
        following replication or recovery.
        Any <literal>%r</> is replaced by the name of the file containing the
        last valid restart point, like in <xref linkend="archive-cleanup-command">.
       </para>
       <para>
        If the command returns a nonzero exit status then a warning log
        message will be written and the database will proceed to start up
        anyway.  An exception is that if the command was terminated by a
        signal or an error by the shell (such as command not found), the
        database will not proceed with startup.
       </para>
      </listitem>
     </varlistentry>

    </variablelist>

  </sect1>

  <sect1 id="recovery-target-settings">

    <title>Recovery Target Settings</title>

     <para>
      By default, recovery will recover to the end of the WAL log. The
      following parameters can be used to specify an earlier stopping point.
      At most one of <varname>recovery_target</>,
      <varname>recovery_target_lsn</>,  <varname>recovery_target_name</>, <varname>recovery_target_time</>,
      <varname>recovery_target_xid</> or <varname>recovery_target_barrier</> can be used; if more than one of these
      is specified in the configuration file, the last entry will be used.
     </para>

     <variablelist>
     <varlistentry id="recovery-target" xreflabel="recovery_target">
      <term><varname>recovery_target</varname><literal> = 'immediate'</literal>
      <indexterm>
        <primary><varname>recovery_target</> recovery parameter</primary>
      </indexterm>
      </term>
      <listitem>
       <para>
        This parameter specifies that recovery should end as soon as a
        consistent state is reached, i.e. as early as possible. When restoring
        from an online backup, this means the point where taking the backup
        ended.
       </para>
       <para>
        Technically, this is a string parameter, but <literal>'immediate'</>
        is currently the only allowed value.
       </para>
      </listitem>
     </varlistentry>

     <varlistentry id="recovery-target-name" xreflabel="recovery_target_name">
      <term><varname>recovery_target_name</varname> (<type>string</type>)
      <indexterm>
        <primary><varname>recovery_target_name</> recovery parameter</primary>
      </indexterm>
      </term>
      <listitem>
       <para>
        This parameter specifies the named restore point (created with
        <function>pg_create_restore_point()</>) to which recovery will proceed.
       </para>
      </listitem>
     </varlistentry>

     <varlistentry id="recovery-target-time" xreflabel="recovery_target_time">
      <term><varname>recovery_target_time</varname> (<type>timestamp</type>)
      <indexterm>
        <primary><varname>recovery_target_time</> recovery parameter</primary>
      </indexterm>
      </term>
      <listitem>
       <para>
        This parameter specifies the time stamp up to which recovery
        will proceed.
        The precise stopping point is also influenced by
        <xref linkend="recovery-target-inclusive">.
       </para>
      </listitem>
     </varlistentry>

     <varlistentry id="recovery-target-xid" xreflabel="recovery_target_xid">
      <term><varname>recovery_target_xid</varname> (<type>string</type>)
      <indexterm>
        <primary><varname>recovery_target_xid</> recovery parameter</primary>
      </indexterm>
      </term>
      <listitem>
       <para>
        This parameter specifies the transaction ID up to which recovery
        will proceed. Keep in mind
        that while transaction IDs are assigned sequentially at transaction
        start, transactions can complete in a different numeric order.
        The transactions that will be recovered are those that committed
        before (and optionally including) the specified one.
        The precise stopping point is also influenced by
        <xref linkend="recovery-target-inclusive">.
       </para>
      </listitem>
     </varlistentry>
     <varlistentry id="recovery-target-barrier" xreflabel="recovery_target_barrier">
      <term><varname>recovery_target_barrier</varname> (<type>string</type>)
       <indexterm>
         <primary><varname>recovery_target_barrier</> recovery parameter</primary>
       </indexterm>
      </term>
      <listitem>
       <para>
        This parameter specifies the barrier ID up to which recovery
        will proceed. A global consistency is guaranteed when recovery is
        stopped at a previously successfully completed barrier. At most
        one of <varname>recovery_target_xid</>,
        <xref linkend="recovery-target-time"> and 
        <varname>recovery_target_barrier</> can be specified.
       </para>
      </listitem>
     </varlistentry>

     <varlistentry id="recovery-target-lsn" xreflabel="recovery_target_lsn">
      <term><varname>recovery_target_lsn</varname> (<type>pg_lsn</type>)
      <indexterm>
        <primary><varname>recovery_target_lsn</> recovery parameter</primary>
      </indexterm>
      </term>
      <listitem>
       <para>
        This parameter specifies the LSN of the 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</></link>.
       </para>
      </listitem>
     </varlistentry>
     </variablelist>

     <para>
       The following options further specify the recovery target, and affect
       what happens when the target is reached:
     </para>

     <variablelist>
     <varlistentry id="recovery-target-inclusive"
                   xreflabel="recovery_target_inclusive">
      <term><varname>recovery_target_inclusive</varname> (<type>boolean</type>)
      <indexterm>
        <primary><varname>recovery_target_inclusive</> recovery parameter</primary>
      </indexterm>
      </term>
      <listitem>
       <para>
        Specifies whether to stop just after the specified recovery target
        (<literal>true</literal>), or just before the recovery target
        (<literal>false</literal>).
        Applies when either <xref linkend="recovery-target-time">
        or <xref linkend="recovery-target-xid"> is specified.
        This setting controls whether transactions
        having exactly the target commit time or ID, respectively, will
        be included in the recovery.  Default is <literal>true</>.
       </para>
      </listitem>
     </varlistentry>

     <varlistentry id="recovery-target-timeline"
                   xreflabel="recovery_target_timeline">
      <term><varname>recovery_target_timeline</varname> (<type>string</type>)
      <indexterm>
        <primary><varname>recovery_target_timeline</> recovery parameter</primary>
      </indexterm>
      </term>
      <listitem>
       <para>
        Specifies recovering into a particular timeline.  The default is
        to recover along the same timeline that was current when the
        base backup was taken. Setting this to <literal>latest</> recovers
        to the latest timeline found in the archive, which is useful in
        a standby server. Other than that you only need to set this parameter
        in complex re-recovery situations, where you need to return to
        a state that itself was reached after a point-in-time recovery.
        See <xref linkend="backup-timelines"> for discussion.
       </para>
      </listitem>
     </varlistentry>

     <varlistentry id="recovery-target-action"
                   xreflabel="recovery_target_action">
      <term><varname>recovery_target_action</varname> (<type>enum</type>)
      <indexterm>
        <primary><varname>recovery_target_action</> recovery parameter</primary>
      </indexterm>
      </term>
      <listitem>
       <para>
        Specifies what action the server should take once the recovery target is
        reached. The default is <literal>pause</>, which means recovery will
        be paused. <literal>promote</> means the recovery process will finish
        and the server will start to accept connections.
        Finally <literal>shutdown</> will stop the server after reaching the
        recovery target.
       </para>
       <para>
        The intended use of the <literal>pause</> setting is to allow queries
        to be executed against the database to check if this recovery target
        is the most desirable point for recovery.
        The paused state can be resumed by
        using <function>pg_wal_replay_resume()</> (see
        <xref linkend="functions-recovery-control-table">), which then
        causes recovery to end. If this recovery target is not the
        desired stopping point, then shut down the server, change the
        recovery target settings to a later target and restart to
        continue recovery.
       </para>
       <para>
        The <literal>shutdown</> setting is useful to have the instance ready
        at the exact replay point desired.  The instance will still be able to
        replay more WAL records (and in fact will have to replay WAL records
        since the last checkpoint next time it is started).
       </para>
       <para>
        Note that because <filename>recovery.conf</> will not be renamed when
        <varname>recovery_target_action</> is set to <literal>shutdown</>,
        any subsequent start will end with immediate shutdown unless the
        configuration is changed or the <filename>recovery.conf</> file is
        removed manually.
       </para>
       <para>
        This setting has no effect if no recovery target is set.
        If <xref linkend="guc-hot-standby"> is not enabled, a setting of
        <literal>pause</> will act the same as <literal>shutdown</>.
       </para>
      </listitem>
     </varlistentry>

    </variablelist>
   </sect1>

  <sect1 id="standby-settings">

    <title>Standby Server Settings</title>
     <variablelist>

       <varlistentry id="standby-mode" xreflabel="standby_mode">
        <term><varname>standby_mode</varname> (<type>boolean</type>)
        <indexterm>
          <primary><varname>standby_mode</> recovery parameter</primary>
        </indexterm>
        </term>
        <listitem>
         <para>
          Specifies whether to start the <productname>PostgreSQL</> server as
          a standby. If this parameter is <literal>on</>, the server will
          not stop recovery when the end of archived WAL is reached, but
          will keep trying to continue recovery by fetching new WAL segments
          using <varname>restore_command</>
          and/or by connecting to the primary server as specified by the
          <varname>primary_conninfo</> setting.
         </para>
        </listitem>
       </varlistentry>
       <varlistentry id="primary-conninfo" xreflabel="primary_conninfo">
        <term><varname>primary_conninfo</varname> (<type>string</type>)
        <indexterm>
          <primary><varname>primary_conninfo</> recovery parameter</primary>
        </indexterm>
        </term>
        <listitem>
         <para>
          Specifies a connection string to be used for the standby server
          to connect with the primary. This string is in the format
          described in <xref linkend="libpq-connstring">. If any option is
          unspecified in this string, then the corresponding environment
          variable (see <xref linkend="libpq-envars">) is checked. If the
          environment variable is not set either, then
          defaults are used.
         </para>
         <para>
          The connection string should specify the host name (or address)
          of the primary server, as well as the port number if it is not
          the same as the standby server's default.
          Also specify a user name corresponding to a suitably-privileged role
          on the primary (see
          <xref linkend="streaming-replication-authentication">).
          A password needs to be provided too, if the primary demands password
          authentication.  It can be provided in the
          <varname>primary_conninfo</varname> string, or in a separate
          <filename>~/.pgpass</> file on the standby server (use
          <literal>replication</> as the database name).
          Do not specify a database name in the
          <varname>primary_conninfo</varname> string.
         </para>
         <para>
          This setting has no effect if <varname>standby_mode</> is <literal>off</>.
         </para>
        </listitem>
       </varlistentry>
       <varlistentry id="primary-slot-name" xreflabel="primary_slot_name">
        <term><varname>primary_slot_name</varname> (<type>string</type>)
        <indexterm>
          <primary><varname>primary_slot_name</> recovery parameter</primary>
        </indexterm>
        </term>
        <listitem>
         <para>
          Optionally specifies an existing replication slot to be used when
          connecting to the primary via streaming replication to control
          resource removal on the upstream node
          (see <xref linkend="streaming-replication-slots">).
          This setting has no effect if <varname>primary_conninfo</> is not
          set.
         </para>
        </listitem>
       </varlistentry>
       <varlistentry id="trigger-file" xreflabel="trigger_file">
        <term><varname>trigger_file</varname> (<type>string</type>)
        <indexterm>
          <primary><varname>trigger_file</> recovery parameter</primary>
        </indexterm>
        </term>
        <listitem>
         <para>
          Specifies a trigger file whose presence ends recovery in the
          standby.  Even if this value is not set, you can still promote
          the standby using <command>pg_ctl promote</>.
          This setting has no effect if <varname>standby_mode</> is <literal>off</>.
         </para>
        </listitem>
       </varlistentry>

     <varlistentry id="recovery-min-apply-delay" xreflabel="recovery_min_apply_delay">
      <term><varname>recovery_min_apply_delay</varname> (<type>integer</type>)
      <indexterm>
        <primary><varname>recovery_min_apply_delay</> recovery parameter</primary>
      </indexterm>
      </term>
      <listitem>
       <para>
        By default, a standby server restores WAL records from the
        primary as soon as possible. It may be useful to have a time-delayed
        copy of the data, offering opportunities to correct data loss errors.
        This parameter allows you to delay recovery by a fixed period of time,
        measured in milliseconds if no unit is specified.  For example, if
        you set this parameter to <literal>5min</literal>, the standby will
        replay each transaction commit only when the system time on the standby
        is at least five minutes past the commit time reported by the master.
       </para>
       <para>
        It is possible that the replication delay between servers exceeds the
        value of this parameter, in which case no delay is added.
        Note that the delay is calculated between the WAL time stamp as written
        on master and the current time on the standby. Delays in transfer
        because of network lag or cascading replication configurations
        may reduce the actual wait time significantly. If the system
        clocks on master and standby are not synchronized, this may lead to
        recovery applying records earlier than expected; but that is not a
        major issue because useful settings of this parameter are much larger
        than typical time deviations between servers.
       </para>
       <para>
        The delay occurs only on WAL records for transaction commits.
        Other records are replayed as quickly as possible, which
        is not a problem because MVCC visibility rules ensure their effects
        are not visible until the corresponding commit record is applied.
       </para>
       <para>
        The delay occurs once the database in recovery has reached a consistent
        state, until the standby is promoted or triggered. After that the standby
        will end recovery without further waiting.
       </para>
       <para>
        This parameter is intended for use with streaming replication deployments;
        however, if the parameter is specified it will be honored in all cases.

        <varname>hot_standby_feedback</> will be delayed by use of this feature
        which could lead to bloat on the master; use both together with care.

        <warning>
         <para>
          Synchronous replication is affected by this setting when <varname>synchronous_commit</varname>
          is set to <literal>remote_apply</literal>; every <literal>COMMIT</literal>
          will need to wait to be applied.
         </para>
        </warning>
       </para>
      </listitem>
     </varlistentry>

     </variablelist>
   </sect1>

</chapter>