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

       <para>
        It is important for the command to return a zero exit status
        only if it succeeds.  The command <emphasis>will</> be asked for file
        names that are not present in the archive; it must return nonzero
        when so asked.  Examples:
<programlisting>
restore_command = 'cp /mnt/server/archivedir/%f "%p"'
restore_command = 'copy "C:\\server\\archivedir\\%f" "%p"'  # Windows
</programlisting>
       </para>
      </listitem>
     </varlistentry>

     <varlistentry id="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 non-zero exit status then a WARNING log
        message will be written.
       </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 non-zero exit status then a WARNING log
        message will be written and the database will proceed to start up
        anyway.  An exception is that if the command was terminated by a
        signal, the database will not proceed with startup.
       </para>
      </listitem>
     </varlistentry>

    </variablelist>

  </sect1>

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

    <title>Recovery Target Settings</title>
     <variablelist>

     <varlistentry id="recovery-target-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.
        At most one of <varname>recovery_target_name</>,
        <xref linkend="recovery-target-time"> or
        <xref linkend="recovery-target-xid"> can be specified.  The default is to
        recover to the end of the WAL log.
       </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.
        At most one of <varname>recovery_target_time</>,
        <xref linkend="recovery-target-name"> or
        <xref linkend="recovery-target-xid"> can be specified.
        The default is to recover to the end of the WAL log.
        The precise stopping point is also influenced by
        <xref linkend="recovery-target-inclusive">.
       </para>
      </listitem>
     </varlistentry>

     <varlistentry id="recovery-target-xid" xreflabel="recovery_target_xid">
      <term><varname>recovery_target_xid</varname> (<type>string</type>)</term>
      <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.
        At most one of <varname>recovery_target_xid</>,
        <xref linkend="recovery-target-name"> or
        <xref linkend="recovery-target-time"> can be specified.
        The default is to recover to the end of the WAL log.
        The precise stopping point is also influenced by
        <xref linkend="recovery-target-inclusive">.
       </para>
      </listitem>
     </varlistentry>

     <varlistentry id="recovery-target-inclusive"
                   xreflabel="recovery_target_inclusive">
      <term><varname>recovery_target_inclusive</varname>
        (<type>boolean</type>)
      </term>
      <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="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>

     </variablelist>
   </sect1>

</chapter>