1<!-- doc/src/sgml/pgstandby.sgml -->
2
3<refentry id="pgstandby">
4 <indexterm zone="pgstandby">
5  <primary>pg_standby</primary>
6 </indexterm>
7
8 <refmeta>
9  <refentrytitle><application>pg_standby</application></refentrytitle>
10  <manvolnum>1</manvolnum>
11  <refmiscinfo>Application</refmiscinfo>
12 </refmeta>
13
14 <refnamediv>
15  <refname>pg_standby</refname>
16  <refpurpose>supports the creation of a <productname>PostgreSQL</productname> warm standby server</refpurpose>
17 </refnamediv>
18
19 <refsynopsisdiv>
20  <cmdsynopsis>
21   <command>pg_standby</command>
22   <arg rep="repeat"><replaceable>option</replaceable></arg>
23   <arg choice="plain"><replaceable>archivelocation</replaceable></arg>
24   <arg choice="plain"><replaceable>nextwalfile</replaceable></arg>
25   <arg choice="plain"><replaceable>walfilepath</replaceable></arg>
26   <arg choice="opt"><replaceable>restartwalfile</replaceable></arg>
27  </cmdsynopsis>
28 </refsynopsisdiv>
29
30 <refsect1>
31  <title>Description</title>
32
33 <para>
34  <application>pg_standby</application> supports creation of a <quote>warm standby</quote>
35  database server.  It is designed to be a production-ready program, as well
36  as a customizable template should you require specific modifications.
37 </para>
38
39 <para>
40  <application>pg_standby</application> is designed to be a waiting
41  <varname>restore_command</varname>, which is needed to turn a standard
42  archive recovery into a warm standby operation.  Other
43  configuration is required as well, all of which is described in the main
44  server manual (see <xref linkend="warm-standby"/>).
45 </para>
46
47  <para>
48   To configure a standby
49   server to use <application>pg_standby</application>, put this into its
50   <filename>postgresql.conf</filename> configuration file:
51<programlisting>
52restore_command = 'pg_standby <replaceable>archiveDir</replaceable> %f %p %r'
53</programlisting>
54   where <replaceable>archiveDir</replaceable> is the directory from which WAL segment
55   files should be restored.
56  </para>
57  <para>
58   If <replaceable>restartwalfile</replaceable> is specified, normally by using the
59   <literal>%r</literal> macro, then all WAL files logically preceding this
60   file will be removed from <replaceable>archivelocation</replaceable>. This minimizes
61   the number of files that need to be retained, while preserving
62   crash-restart capability.  Use of this parameter is appropriate if the
63   <replaceable>archivelocation</replaceable> is a transient staging area for this
64   particular standby server, but <emphasis>not</emphasis> when the
65   <replaceable>archivelocation</replaceable> is intended as a long-term WAL archive area.
66  </para>
67  <para>
68   <application>pg_standby</application> assumes that
69   <replaceable>archivelocation</replaceable> is a directory readable by the
70   server-owning user.  If <replaceable>restartwalfile</replaceable> (or <literal>-k</literal>)
71   is specified,
72   the <replaceable>archivelocation</replaceable> directory must be writable too.
73  </para>
74  <para>
75   There are two ways to fail over to a <quote>warm standby</quote> database server
76   when the master server fails:
77
78   <variablelist>
79    <varlistentry>
80     <term>Smart Failover</term>
81     <listitem>
82      <para>
83       In smart failover, the server is brought up after applying all WAL
84       files available in the archive. This results in zero data loss, even if
85       the standby server has fallen behind, but if there is a lot of
86       unapplied WAL it can be a long time before the standby server becomes
87       ready. To trigger a smart failover, create a trigger file containing
88       the word <literal>smart</literal>, or just create it and leave it empty.
89      </para>
90     </listitem>
91    </varlistentry>
92    <varlistentry>
93     <term>Fast Failover</term>
94     <listitem>
95      <para>
96       In fast failover, the server is brought up immediately. Any WAL files
97       in the archive that have not yet been applied will be ignored, and
98       all transactions in those files are lost. To trigger a fast failover,
99       create a trigger file and write the word <literal>fast</literal> into it.
100       <application>pg_standby</application> can also be configured to execute a fast
101       failover automatically if no new WAL file appears within a defined
102       interval.
103      </para>
104     </listitem>
105    </varlistentry>
106   </variablelist>
107  </para>
108
109 </refsect1>
110
111 <refsect1>
112  <title>Options</title>
113
114   <para>
115    <application>pg_standby</application> accepts the following command-line arguments:
116
117    <variablelist>
118
119     <varlistentry>
120      <term><option>-c</option></term>
121      <listitem>
122       <para>
123        Use <literal>cp</literal> or <literal>copy</literal> command to restore WAL files
124        from archive.  This is the only supported behavior so this option is useless.
125       </para>
126      </listitem>
127     </varlistentry>
128
129     <varlistentry>
130      <term><option>-d</option></term>
131      <listitem>
132       <para>
133        Print lots of debug logging output on <filename>stderr</filename>.
134       </para>
135      </listitem>
136     </varlistentry>
137
138     <varlistentry>
139      <term><option>-k</option></term>
140      <listitem>
141       <para>
142        Remove files from <replaceable>archivelocation</replaceable> so that
143        no more than this many WAL files before the current one are kept in the
144        archive.  Zero (the default) means not to remove any files from
145        <replaceable>archivelocation</replaceable>.
146        This parameter will be silently ignored if
147        <replaceable>restartwalfile</replaceable> is specified, since that
148        specification method is more accurate in determining the correct
149        archive cut-off point.
150        Use of this parameter is <emphasis>deprecated</emphasis> as of
151        <productname>PostgreSQL</productname> 8.3; it is safer and more efficient to
152        specify a <replaceable>restartwalfile</replaceable> parameter.  A too
153        small setting could result in removal of files that are still needed
154        for a restart of the standby server, while a too large setting wastes
155        archive space.
156       </para>
157      </listitem>
158     </varlistentry>
159
160     <varlistentry>
161      <term><option>-r</option> <replaceable>maxretries</replaceable></term>
162      <listitem>
163       <para>
164        Set the maximum number of times to retry the copy command if
165        it fails (default 3). After each failure, we wait for
166        <replaceable>sleeptime</replaceable> * <replaceable>num_retries</replaceable>
167        so that the wait time increases progressively.  So by default,
168        we will wait 5 secs, 10 secs, then 15 secs before reporting
169        the failure back to the standby server. This will be
170        interpreted as end of recovery and the standby will come
171        up fully as a result.
172       </para>
173      </listitem>
174     </varlistentry>
175
176     <varlistentry>
177      <term><option>-s</option> <replaceable>sleeptime</replaceable></term>
178      <listitem>
179       <para>
180        Set the number of seconds (up to 60, default 5) to sleep between
181        tests to see if the WAL file to be restored is available in
182        the archive yet.  The default setting is not necessarily
183        recommended; consult <xref linkend="warm-standby"/> for discussion.
184       </para>
185      </listitem>
186     </varlistentry>
187
188     <varlistentry>
189      <term><option>-t</option> <replaceable>triggerfile</replaceable></term>
190      <listitem>
191       <para>
192        Specify a trigger file whose presence should cause failover.
193        It is recommended that you use a structured file name to
194        avoid confusion as to which server is being triggered
195        when multiple servers exist on the same system; for example
196        <filename>/tmp/pgsql.trigger.5432</filename>.
197       </para>
198      </listitem>
199     </varlistentry>
200
201     <varlistentry>
202      <term><option>-V</option></term>
203      <term><option>--version</option></term>
204      <listitem>
205       <para>
206        Print the <application>pg_standby</application> version and exit.
207       </para>
208      </listitem>
209     </varlistentry>
210
211     <varlistentry>
212      <term><option>-w</option> <replaceable>maxwaittime</replaceable></term>
213      <listitem>
214       <para>
215        Set the maximum number of seconds to wait for the next WAL file,
216        after which a fast failover will be performed.
217        A setting of zero (the default) means wait forever.
218        The default setting is not necessarily recommended;
219        consult <xref linkend="warm-standby"/> for discussion.
220       </para>
221      </listitem>
222     </varlistentry>
223
224     <varlistentry>
225      <term><option>-?</option></term>
226      <term><option>--help</option></term>
227      <listitem>
228       <para>
229        Show help about <application>pg_standby</application> command line
230        arguments, and exit.
231       </para>
232      </listitem>
233     </varlistentry>
234    </variablelist>
235   </para>
236
237 </refsect1>
238
239 <refsect1>
240  <title>Notes</title>
241
242  <para>
243   <application>pg_standby</application> is designed to work with
244   <productname>PostgreSQL</productname> 8.2 and later.
245  </para>
246  <para>
247   <productname>PostgreSQL</productname> 8.3 provides the <literal>%r</literal> macro,
248   which is designed to let <application>pg_standby</application> know the
249   last file it needs to keep.  With <productname>PostgreSQL</productname> 8.2, the
250   <literal>-k</literal> option must be used if archive cleanup is
251   required.  This option remains available in 8.3, but its use is deprecated.
252  </para>
253  <para>
254   <productname>PostgreSQL</productname> 8.4 provides the
255   <varname>recovery_end_command</varname> option.  Without this option
256   a leftover trigger file can be hazardous.
257  </para>
258
259  <para>
260   <application>pg_standby</application> is written in C and has an
261   easy-to-modify source code, with specifically designated sections to modify
262   for your own needs
263  </para>
264 </refsect1>
265
266 <refsect1>
267  <title>Examples</title>
268
269  <para>On Linux or Unix systems, you might use:
270
271<programlisting>
272archive_command = 'cp %p .../archive/%f'
273
274restore_command = 'pg_standby -d -s 2 -t /tmp/pgsql.trigger.5442 .../archive %f %p %r 2>>standby.log'
275
276recovery_end_command = 'rm -f /tmp/pgsql.trigger.5442'
277</programlisting>
278   where the archive directory is physically located on the standby server,
279   so that the <varname>archive_command</varname> is accessing it across NFS,
280   but the files are local to the standby (enabling use of <literal>ln</literal>).
281   This will:
282  <itemizedlist>
283   <listitem>
284    <para>
285     produce debugging output in <filename>standby.log</filename>
286    </para>
287   </listitem>
288   <listitem>
289    <para>
290     sleep for 2 seconds between checks for next WAL file availability
291    </para>
292   </listitem>
293   <listitem>
294    <para>
295     stop waiting only when a trigger file called
296     <filename>/tmp/pgsql.trigger.5442</filename> appears,
297     and perform failover according to its content
298    </para>
299   </listitem>
300   <listitem>
301    <para>
302     remove the trigger file when recovery ends
303    </para>
304   </listitem>
305   <listitem>
306    <para>
307     remove no-longer-needed files from the archive directory
308    </para>
309   </listitem>
310  </itemizedlist>
311  </para>
312
313  <para>On Windows, you might use:
314
315<programlisting>
316archive_command = 'copy %p ...\\archive\\%f'
317
318restore_command = 'pg_standby -d -s 5 -t C:\pgsql.trigger.5442 ...\archive %f %p %r 2>>standby.log'
319
320recovery_end_command = 'del C:\pgsql.trigger.5442'
321</programlisting>
322   Note that backslashes need to be doubled in the
323   <varname>archive_command</varname>, but <emphasis>not</emphasis> in the
324   <varname>restore_command</varname> or <varname>recovery_end_command</varname>.
325   This will:
326  <itemizedlist>
327   <listitem>
328    <para>
329     use the <literal>copy</literal> command to restore WAL files from archive
330    </para>
331   </listitem>
332   <listitem>
333    <para>
334     produce debugging output in <filename>standby.log</filename>
335    </para>
336   </listitem>
337   <listitem>
338    <para>
339     sleep for 5 seconds between checks for next WAL file availability
340    </para>
341   </listitem>
342   <listitem>
343    <para>
344     stop waiting only when a trigger file called
345     <filename>C:\pgsql.trigger.5442</filename> appears,
346     and perform failover according to its content
347    </para>
348   </listitem>
349   <listitem>
350    <para>
351     remove the trigger file when recovery ends
352    </para>
353   </listitem>
354   <listitem>
355    <para>
356     remove no-longer-needed files from the archive directory
357    </para>
358   </listitem>
359  </itemizedlist>
360  </para>
361
362  <para>
363   The <literal>copy</literal> command on Windows sets the final file size
364   before the file is completely copied, which would ordinarily confuse
365   <application>pg_standby</application>.  Therefore
366   <application>pg_standby</application> waits <replaceable>sleeptime</replaceable>
367   seconds once it sees the proper file size.  GNUWin32's <literal>cp</literal>
368   sets the file size only after the file copy is complete.
369  </para>
370
371  <para>
372   Since the Windows example uses <literal>copy</literal> at both ends, either
373   or both servers might be accessing the archive directory across the
374   network.
375  </para>
376
377 </refsect1>
378
379 <refsect1>
380  <title>Author</title>
381
382  <para>
383   Simon Riggs <email>simon@2ndquadrant.com</email>
384  </para>
385 </refsect1>
386
387 <refsect1>
388  <title>See Also</title>
389
390  <simplelist type="inline">
391   <member><xref linkend="pgarchivecleanup"/></member>
392  </simplelist>
393 </refsect1>
394</refentry>
395