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>)</term>
      <indexterm>
        <primary><varname>restore_command</> recovery parameter</primary>
      </indexterm>
      <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>)</term>
      <indexterm>
        <primary><varname>archive_cleanup_command</> recovery parameter</primary>
      </indexterm>
      <listitem>
       <para>
        This optional parameter specifies a shell command that will be executed
        at every restartpoint.  The purpose of
        <varname>archive_cleanup_command</> is to provide a mechanism for
        cleaning up old archived WAL files that are no longer needed by the
        standby server.
        Any <literal>%r</> is replaced by the name of the file containing the
        last valid restart point.
        That is the earliest file that must be <emphasis>kept</> to allow a
        restore to be restartable, and so all files earlier than <literal>%r</>
        may be safely removed.
        This information can be used to truncate the archive to just the
        minimum required to support restart from the current restore.
        The <xref linkend="pgarchivecleanup"> module
        is often used in <varname>archive_cleanup_command</> for
        single-standby configurations, for example:
<programlisting>archive_cleanup_command = 'pg_archivecleanup /mnt/server/archivedir %r'</programlisting>
        Note however that if multiple standby servers are restoring from the
        same archive directory, you will need to ensure that you do not delete
        WAL files until they are no longer needed by any of the servers.
        <varname>archive_cleanup_command</> would typically be used in a
        warm-standby configuration (see <xref linkend="warm-standby">).
        Write <literal>%%</> to embed an actual <literal>%</> character in the
        command.
       </para>
       <para>
        If the command returns a 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>)</term>
      <indexterm>
        <primary><varname>recovery_end_command</> recovery parameter</primary>
      </indexterm>
      <listitem>
       <para>
        This parameter specifies a shell command that will be executed once only
        at the end of recovery. This parameter is optional. The purpose of the
        <varname>recovery_end_command</> is to provide a mechanism for cleanup
        following replication or recovery.
        Any <literal>%r</> is replaced by the name of the file containing the
        last valid restart point, like in <xref linkend="archive-cleanup-command">.
       </para>
       <para>
        If the command returns a 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_name</>, <varname>recovery_target_time</>, or
      <varname>recovery_target_xid</> can be specified. 
     </para>
     <variablelist>

     <varlistentry id="recovery-target" xreflabel="recovery_target_name">
      <term><varname>recovery_target</varname><literal> = 'immediate'</literal></term>
      <indexterm>
        <primary><varname>recovery_target</> recovery parameter</primary>
      </indexterm>
      <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>)
      </term>
      <indexterm>
        <primary><varname>recovery_target_name</> recovery parameter</primary>
      </indexterm>
      <listitem>
       <para>
        This parameter specifies the named restore point, created with
        <function>pg_create_restore_point()</> to which recovery will proceed.
       </para>
      </listitem>
     </varlistentry>

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

     <varlistentry id="recovery-target-xid" xreflabel="recovery_target_xid">
      <term><varname>recovery_target_xid</varname> (<type>string</type>)</term>
      <indexterm>
        <primary><varname>recovery_target_xid</> recovery parameter</primary>
      </indexterm>
      <listitem>
       <para>
        This parameter specifies the transaction ID up to which recovery
        will proceed. Keep in mind
        that while transaction IDs are assigned sequentially at transaction
        start, transactions can complete in a different numeric order.
        The transactions that will be recovered are those that committed
        before (and optionally including) the specified one.
        The precise stopping point is also influenced by
        <xref linkend="recovery-target-inclusive">.
       </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>)
      </term>
      <indexterm>
        <primary><varname>recovery_target_inclusive</> recovery parameter</primary>
      </indexterm>
      <listitem>
       <para>
        Specifies whether we stop just after the specified recovery target
        (<literal>true</literal>), or just before the recovery target
        (<literal>false</literal>).
        Applies to both <xref linkend="recovery-target-time">
        and <xref linkend="recovery-target-xid">, whichever one is
        specified for this recovery.  This indicates whether transactions
        having exactly the target commit time or ID, respectively, will
        be included in the recovery.  Default is <literal>true</>.
       </para>
      </listitem>
     </varlistentry>

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

     <varlistentry id="pause-at-recovery-target"
                   xreflabel="pause_at_recovery_target">
      <term><varname>pause_at_recovery_target</varname>
        (<type>boolean</type>)
      </term>
      <indexterm>
        <primary><varname>pause_at_recovery_target</> recovery parameter</primary>
      </indexterm>
      <listitem>
       <para>
        Specifies whether recovery should pause when the recovery target
        is reached. The default is true.
        This is intended to allow queries to be executed against the
        database to check if this recovery target is the most desirable
        point for recovery. The paused state can be resumed by using
        <function>pg_xlog_replay_resume()</> (See
        <xref linkend="functions-recovery-control-table">), which then
        causes recovery to end. If this recovery target is not the
        desired stopping point, then shutdown the server, change the
        recovery target settings to a later target and restart to
        continue recovery.
       </para>
       <para>
        This setting has no effect if <xref linkend="guc-hot-standby"> is not
        enabled, or if no recovery target is set.
       </para>
      </listitem>
     </varlistentry>

     </variablelist>
   </sect1>

  <sect1 id="standby-settings">

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

       <varlistentry id="standby-mode" xreflabel="standby_mode">
        <term><varname>standby_mode</varname> (<type>boolean</type>)</term>
        <indexterm>
          <primary><varname>standby_mode</> recovery parameter</primary>
        </indexterm>
        <listitem>
         <para>
          Specifies whether to start the <productname>PostgreSQL</> server as
          a standby. If this parameter is <literal>on</>, the server will
          not stop recovery when the end of archived WAL is reached, but
          will keep trying to continue recovery by fetching new WAL segments
          using <varname>restore_command</>
          and/or by connecting to the primary server as specified by the
          <varname>primary_conninfo</> setting.
         </para>
        </listitem>
       </varlistentry>
       <varlistentry id="primary-conninfo" xreflabel="primary_conninfo">
        <term><varname>primary_conninfo</varname> (<type>string</type>)</term>
        <indexterm>
          <primary><varname>primary_conninfo</> recovery parameter</primary>
        </indexterm>
        <listitem>
         <para>
          Specifies a connection string to be used for the standby server
          to connect with the primary. This string is in the format
          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-slotname" xreflabel="primary_slotname">
        <term><varname>primary_slotname</varname> (<type>string</type>)</term>
        <indexterm>
          <primary><varname>primary_slotname</> recovery parameter</primary>
        </indexterm>
        <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>)</term>
        <indexterm>
          <primary><varname>trigger_file</> recovery parameter</primary>
        </indexterm>
        <listitem>
         <para>
          Specifies a trigger file whose presence ends recovery in the
          standby.  Even if this value is not set, you can still promote
          the standby using <command>pg_ctl promote</>.
          This setting has no effect if <varname>standby_mode</> is <literal>off</>.
         </para>
        </listitem>
       </varlistentry>

     <varlistentry id="min-recovery-apply-delay" xreflabel="min_recovery_apply_delay">
      <term><varname>min_recovery_apply_delay</varname> (<type>integer</type>)</term>
      <indexterm>
        <primary><varname>min_recovery_apply_delay</> recovery parameter</primary>
      </indexterm>
      <listitem>
       <para>
        By default, a standby server keeps restoring WAL records from the
        primary as soon as possible. It may be useful to have a time-delayed
        copy of the data, offering various options to correct data loss errors.
        This parameter allows you to delay recovery by a fixed period of time,
        specified 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 timestamp as written
        on master and the time on the current standby. Delays
        in transfer because of networks or cascading replication configurations
        may reduce the actual wait time significantly. If the system
        clocks on master and standby are not synchronised, this may lead to
        recovery applying records earlier than expected but is not a major issue
        because the useful settings of the parameter are much larger than
        typical time deviation between the servers. Be careful to allow for
        different timezone settings on master and standby.
       </para>
       <para>
        The delay occurs only on WAL records for COMMIT and Restore Points.
        Other records may be replayed earlier than the specified delay, which
        is not an issue for MVCC though may potentially increase the number
        of recovery conflicts generated.
       </para>
       <para>
        The delay occurs 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 honoured in all cases.
        Synchronous replication is not affected by this setting because there is
        not yet any setting to request synchronous apply of transaction commits.
        <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.
       </para>
      </listitem>
     </varlistentry>

     </variablelist>
   </sect1>

</chapter>