doc/src/sgml/pgstandby.sgml

   1 <!-- $PostgreSQL: pgsql/doc/src/sgml/pgstandby.sgml,v 2.6 2008/12/15 22:08:35 momjian Exp $ -->
   2
   3 <sect1 id="pgstandby">
   4  <title>pg_standby</title>
   5
   6  <indexterm zone="pgstandby">
   7   <primary>pg_standby</primary>
   8  </indexterm>
   9
  10  <para>
  11   <application>pg_standby</> supports creation of a <quote>warm standby</>
  12   database server.  It is designed to be a production-ready program, as well
  13   as a customizable template should you require specific modifications.
  14  </para>
  15
  16  <para>
  17   <application>pg_standby</> is designed to be a waiting
  18   <literal>restore_command</literal>, which is needed to turn a standard
  19   archive recovery into a warm standby operation.  Other
  20   configuration is required as well, all of which is described in the main
  21   server manual (see <xref linkend="warm-standby">).
  22  </para>
  23
  24  <para>
  25   <application>pg_standby</application> features include:
  26  </para>
  27  <itemizedlist>
  28   <listitem>
  29    <para>
  30     Supports copy or link for restoring WAL files
  31    </para>
  32   </listitem>
  33   <listitem>
  34    <para>
  35     Written in C, so very portable and easy to install
  36    </para>
  37   </listitem>
  38   <listitem>
  39    <para>
  40     Easy-to-modify source code, with specifically designated
  41     sections to modify for your own needs
  42    </para>
  43   </listitem>
  44   <listitem>
  45    <para>
  46     Already tested on Linux and Windows
  47    </para>
  48   </listitem>
  49  </itemizedlist>
  50
  51  <sect2>
  52   <title>Usage</title>
  53
  54   <para>
  55    To configure a standby
  56    server to use <application>pg_standby</>, put this into its
  57    <filename>recovery.conf</filename> configuration file:
  58   </para>
  59   <programlisting>
  60 restore_command = 'pg_standby <replaceable>archiveDir</> %f %p %r'
  61   </programlisting>
  62   <para>
  63    where <replaceable>archiveDir</> is the directory from which WAL segment
  64    files should be restored.
  65   </para>
  66   <para>
  67    The full syntax of <application>pg_standby</>'s command line is
  68   </para>
  69   <synopsis>
  70 pg_standby <optional> <replaceable>option</> ... </optional> <replaceable>archivelocation</> <replaceable>nextwalfile</> <replaceable>xlogfilepath</> <optional> <replaceable>restartwalfile</> </optional>
  71   </synopsis>
  72   <para>
  73    When used within <literal>restore_command</literal>, the <literal>%f</> and
  74    <literal>%p</> macros should be specified for <replaceable>nextwalfile</>
  75    and <replaceable>xlogfilepath</> respectively, to provide the actual file
  76    and path required for the restore.
  77   </para>
  78   <para>
  79    If <replaceable>restartwalfile</> is specified, normally by using the
  80    <literal>%r</literal> macro, then all WAL files logically preceding this
  81    file will be removed from <replaceable>archivelocation</>. This minimizes
  82    the number of files that need to be retained, while preserving
  83    crash-restart capability.  Use of this parameter is appropriate if the
  84    <replaceable>archivelocation</> is a transient staging area for this
  85    particular standby server, but <emphasis>not</> when the
  86    <replaceable>archivelocation</> is intended as a long-term WAL archive area.
  87   </para>
  88   <para>
  89    <application>pg_standby</application> assumes that
  90    <replaceable>archivelocation</> is a directory readable by the
  91    server-owning user.  If <replaceable>restartwalfile</> (or <literal>-k</>)
  92    is specified,
  93    the <replaceable>archivelocation</> directory must be writable too.
  94   </para>
  95
  96   <table>
  97    <title><application>pg_standby</> options</title>
  98    <tgroup cols="3">
  99      <thead>
 100      <row>
 101       <entry>Option</entry>
 102       <entry>Default</entry>
 103       <entry>Description</entry>
 104      </row>
 105     </thead>
 106     <tbody>
 107      <row>
 108       <entry><literal>-c</></entry>
 109       <entry>yes</entry>
 110       <entry>
 111        Use <literal>cp</> or <literal>copy</> command to restore WAL files
 112        from archive.
 113       </entry>
 114      </row>
 115      <row>
 116       <entry><literal>-d</></entry>
 117       <entry>no</entry>
 118       <entry>Print lots of debug logging output on <filename>stderr</>.</entry>
 119      </row>
 120      <row>
 121       <entry><literal>-k</> <replaceable>numfiles</></entry>
 122       <entry>0</entry>
 123       <entry>
 124        Remove files from <replaceable>archivelocation</replaceable> so that
 125        no more than this many WAL files before the current one are kept in the
 126        archive.  Zero (the default) means not to remove any files from
 127        <replaceable>archivelocation</replaceable>.
 128        This parameter will be silently ignored if
 129        <replaceable>restartwalfile</replaceable> is specified, since that
 130        specification method is more accurate in determining the correct
 131        archive cut-off point.
 132        Use of this parameter is <emphasis>deprecated</> as of
 133        <productname>PostgreSQL</> 8.3; it is safer and more efficient to
 134        specify a <replaceable>restartwalfile</replaceable> parameter.  A too
 135        small setting could result in removal of files that are still needed
 136        for a restart of the standby server, while a too large setting wastes
 137        archive space.
 138       </entry>
 139      </row>
 140      <row>
 141       <entry><literal>-l</></entry>
 142       <entry>no</entry>
 143       <entry>
 144        Use <literal>ln</> command to restore WAL files from archive.
 145        Link is more efficient than copy, but the default is copy since link
 146        will not work in all scenarios.
 147        On Windows, this option uses the <literal>mklink</> command
 148        to provide a file-to-file symbolic link. <literal>-l</> will
 149        not work on versions of Windows prior to Vista.
 150       </entry>
 151      </row>
 152      <row>
 153       <entry><literal>-r</> <replaceable>maxretries</></entry>
 154       <entry>3</entry>
 155       <entry>
 156         Set the maximum number of times to retry the copy or link command if it
 157         fails. After each failure, we wait for <replaceable>sleeptime</> *
 158         <replaceable>num_retries</>
 159         so that the wait time increases progressively.  So by default,
 160         we will wait 5 secs, 10 secs, then 15 secs before reporting
 161         the failure back to the standby server. This will be
 162         interpreted as end of recovery and the standby will come
 163         up fully as a result.
 164       </entry>
 165      </row>
 166      <row>
 167       <entry><literal>-s</> <replaceable>sleeptime</></entry>
 168       <entry>5</entry>
 169       <entry>
 170        Set the number of seconds (up to 60) to sleep between tests to see
 171        if the WAL file to be restored is available in the archive yet.
 172        The default setting is not necessarily recommended;
 173        consult <xref linkend="warm-standby"> for discussion.
 174       </entry>
 175      </row>
 176      <row>
 177       <entry><literal>-t</> <replaceable>triggerfile</></entry>
 178       <entry>none</entry>
 179       <entry>
 180        Specify a trigger file whose presence should cause recovery to end
 181        whether or not the next WAL file is available.
 182        It is recommended that you use a structured filename to
 183        avoid confusion as to which server is being triggered
 184        when multiple servers exist on the same system; for example
 185        <filename>/tmp/pgsql.trigger.5432</>.
 186       </entry>
 187      </row>
 188      <row>
 189       <entry><literal>-w</> <replaceable>maxwaittime</></entry>
 190       <entry>0</entry>
 191       <entry>
 192        Set the maximum number of seconds to wait for the next WAL file,
 193        after which recovery will end and the standby will come up.
 194        A setting of zero (the default) means wait forever.
 195        The default setting is not necessarily recommended;
 196        consult <xref linkend="warm-standby"> for discussion.
 197       </entry>
 198      </row>
 199     </tbody>
 200    </tgroup>
 201   </table>
 202   <note>
 203    <para>
 204     <literal>--help</literal> is not supported since
 205     <application>pg_standby</application> is not intended for interactive use,
 206     except during development and testing.
 207    </para>
 208   </note>
 209  </sect2>
 210
 211  <sect2>
 212   <title>Examples</title>
 213
 214   <para>On Linux or Unix systems, you might use:</para>
 215
 216   <programlisting>
 217 archive_command = 'cp %p .../archive/%f'
 218
 219 restore_command = 'pg_standby -l -d -s 2 -t /tmp/pgsql.trigger.5442 .../archive %f %p %r 2>>standby.log'
 220   </programlisting>
 221   <para>
 222    where the archive directory is physically located on the standby server,
 223    so that the <literal>archive_command</> is accessing it across NFS,
 224    but the files are local to the standby (enabling use of <literal>ln</>).
 225    This will:
 226   </para>
 227   <itemizedlist>
 228    <listitem>
 229     <para>
 230      use the <literal>ln</> command to restore WAL files from archive
 231     </para>
 232    </listitem>
 233    <listitem>
 234     <para>
 235      produce debugging output in <filename>standby.log</>
 236     </para>
 237    </listitem>
 238    <listitem>
 239     <para>
 240      sleep for 2 seconds between checks for next WAL file availability
 241     </para>
 242    </listitem>
 243    <listitem>
 244     <para>
 245      stop waiting only when a trigger file called
 246      <filename>/tmp/pgsql.trigger.5442</> appears
 247     </para>
 248    </listitem>
 249    <listitem>
 250     <para>
 251      remove no-longer-needed files from the archive directory
 252     </para>
 253    </listitem>
 254   </itemizedlist>
 255
 256   <para>On Windows, you might use:</para>
 257
 258   <programlisting>
 259 archive_command = 'copy %p ...\\archive\\%f'
 260
 261 restore_command = 'pg_standby -d -s 5 -t C:\pgsql.trigger.5442 ...\archive %f %p %r 2>>standby.log'
 262   </programlisting>
 263   <para>
 264    Note that backslashes need to be doubled in the
 265    <literal>archive_command</>, but <emphasis>not</emphasis> in the
 266    <literal>restore_command</>.  This will:
 267   </para>
 268   <itemizedlist>
 269    <listitem>
 270     <para>
 271      use the <literal>copy</> command to restore WAL files from archive
 272     </para>
 273    </listitem>
 274    <listitem>
 275     <para>
 276      produce debugging output in <filename>standby.log</>
 277     </para>
 278    </listitem>
 279    <listitem>
 280     <para>
 281      sleep for 5 seconds between checks for next WAL file availability
 282     </para>
 283    </listitem>
 284    <listitem>
 285     <para>
 286      stop waiting only when a trigger file called
 287      <filename>C:\pgsql.trigger.5442</> appears
 288     </para>
 289    </listitem>
 290    <listitem>
 291     <para>
 292      remove no-longer-needed files from the archive directory
 293     </para>
 294    </listitem>
 295   </itemizedlist>
 296
 297   <para>
 298    The <literal>copy</> command on Windows sets the final file size
 299    before the file is completely copied, which would ordinarly confuse
 300    <application>pg_standby</application>.  Therefore
 301    <application>pg_standby</application> waits <literal>sleeptime</>
 302    seconds once it sees the proper file size.  GNUWin32's <literal>cp</>
 303    sets the file size only after the file copy is complete.
 304   </para>
 305
 306   <para>
 307    Using the Since the Windows example uses <literal>copy</> at both ends, either
 308    or both servers might be accessing the archive directory across the
 309    network.
 310   </para>
 311
 312  </sect2>
 313
 314  <sect2>
 315   <title>Supported server versions</title>
 316
 317   <para>
 318    <application>pg_standby</application> is designed to work with
 319    <productname>PostgreSQL</> 8.2 and later.
 320   </para>
 321   <para>
 322    <productname>PostgreSQL</> 8.3 provides the <literal>%r</literal> macro,
 323    which is designed to let <application>pg_standby</application> know the
 324    last file it needs to keep.  With <productname>PostgreSQL</> 8.2, the
 325    <literal>-k</literal> option must be used if archive cleanup is
 326    required.  This option remains available in 8.3, but its use is deprecated.
 327   </para>
 328  </sect2>
 329
 330  <sect2>
 331   <title>Author</title>
 332
 333   <para>
 334    Simon Riggs <email>simon@2ndquadrant.com</email>
 335   </para>
 336  </sect2>
 337
 338 </sect1>