1PG_STANDBY(1)           PostgreSQL 9.2.24 Documentation          PG_STANDBY(1)
2
3
4

NAME

6       pg_standby - supports the creation of a PostgreSQL warm standby server
7

SYNOPSIS

9       pg_standby [option...] archivelocation nextwalfile xlogfilepath
10                  [restartwalfile]
11

DESCRIPTION

13       pg_standby supports creation of a “warm standby” database server. It is
14       designed to be a production-ready program, as well as a customizable
15       template should you require specific modifications.
16
17       pg_standby is designed to be a waiting restore_command, which is needed
18       to turn a standard archive recovery into a warm standby operation.
19       Other configuration is required as well, all of which is described in
20       the main server manual (see Section 25.2, “Log-Shipping Standby
21       Servers”, in the documentation).
22
23       To configure a standby server to use pg_standby, put this into its
24       recovery.conf configuration file:
25
26           restore_command = 'pg_standby archiveDir %f %p %r'
27
28       where archiveDir is the directory from which WAL segment files should
29       be restored.
30
31       If restartwalfile is specified, normally by using the %r macro, then
32       all WAL files logically preceding this file will be removed from
33       archivelocation. This minimizes the number of files that need to be
34       retained, while preserving crash-restart capability. Use of this
35       parameter is appropriate if the archivelocation is a transient staging
36       area for this particular standby server, but not when the
37       archivelocation is intended as a long-term WAL archive area.
38
39       pg_standby assumes that archivelocation is a directory readable by the
40       server-owning user. If restartwalfile (or -k) is specified, the
41       archivelocation directory must be writable too.
42
43       There are two ways to fail over to a “warm standby” database server
44       when the master server fails:
45
46       Smart Failover
47           In smart failover, the server is brought up after applying all WAL
48           files available in the archive. This results in zero data loss,
49           even if the standby server has fallen behind, but if there is a lot
50           of unapplied WAL it can be a long time before the standby server
51           becomes ready. To trigger a smart failover, create a trigger file
52           containing the word smart, or just create it and leave it empty.
53
54       Fast Failover
55           In fast failover, the server is brought up immediately. Any WAL
56           files in the archive that have not yet been applied will be
57           ignored, and all transactions in those files are lost. To trigger a
58           fast failover, create a trigger file and write the word fast into
59           it.  pg_standby can also be configured to execute a fast failover
60           automatically if no new WAL file appears within a defined interval.
61

OPTIONS

63       pg_standby accepts the following command-line arguments:
64
65       -c
66           Use cp or copy command to restore WAL files from archive. This is
67           the only supported behavior so this option is useless.
68
69       -d
70           Print lots of debug logging output on stderr.
71
72       -k
73           Remove files from archivelocation so that no more than this many
74           WAL files before the current one are kept in the archive. Zero (the
75           default) means not to remove any files from archivelocation. This
76           parameter will be silently ignored if restartwalfile is specified,
77           since that specification method is more accurate in determining the
78           correct archive cut-off point. Use of this parameter is deprecated
79           as of PostgreSQL 8.3; it is safer and more efficient to specify a
80           restartwalfile parameter. A too small setting could result in
81           removal of files that are still needed for a restart of the standby
82           server, while a too large setting wastes archive space.
83
84       -r maxretries
85           Set the maximum number of times to retry the copy command if it
86           fails (default 3). After each failure, we wait for sleeptime *
87           num_retries so that the wait time increases progressively. So by
88           default, we will wait 5 secs, 10 secs, then 15 secs before
89           reporting the failure back to the standby server. This will be
90           interpreted as end of recovery and the standby will come up fully
91           as a result.
92
93       -s sleeptime
94           Set the number of seconds (up to 60, default 5) to sleep between
95           tests to see if the WAL file to be restored is available in the
96           archive yet. The default setting is not necessarily recommended;
97           consult Section 25.2, “Log-Shipping Standby Servers”, in the
98           documentation for discussion.
99
100       -t triggerfile
101           Specify a trigger file whose presence should cause failover. It is
102           recommended that you use a structured file name to avoid confusion
103           as to which server is being triggered when multiple servers exist
104           on the same system; for example /tmp/pgsql.trigger.5432.
105
106       -V, --version
107           Print the pg_standby version and exit.
108
109       -w maxwaittime
110           Set the maximum number of seconds to wait for the next WAL file,
111           after which a fast failover will be performed. A setting of zero
112           (the default) means wait forever. The default setting is not
113           necessarily recommended; consult Section 25.2, “Log-Shipping
114           Standby Servers”, in the documentation for discussion.
115
116       -?, --help
117           Show help about pg_standby command line arguments, and exit.
118

NOTES

120       pg_standby is designed to work with PostgreSQL 8.2 and later.
121
122       PostgreSQL 8.3 provides the %r macro, which is designed to let
123       pg_standby know the last file it needs to keep. With PostgreSQL 8.2,
124       the -k option must be used if archive cleanup is required. This option
125       remains available in 8.3, but its use is deprecated.
126
127       PostgreSQL 8.4 provides the recovery_end_command option. Without this
128       option a leftover trigger file can be hazardous.
129
130       pg_standby is written in C and has an easy-to-modify source code, with
131       specifically designated sections to modify for your own needs
132

EXAMPLES

134       On Linux or Unix systems, you might use:
135
136           archive_command = 'cp %p .../archive/%f'
137
138           restore_command = 'pg_standby -d -s 2 -t /tmp/pgsql.trigger.5442 .../archive %f %p %r 2>>standby.log'
139
140           recovery_end_command = 'rm -f /tmp/pgsql.trigger.5442'
141
142       where the archive directory is physically located on the standby
143       server, so that the archive_command is accessing it across NFS, but the
144       files are local to the standby (enabling use of ln). This will:
145
146       ·   produce debugging output in standby.log
147
148       ·   sleep for 2 seconds between checks for next WAL file availability
149
150       ·   stop waiting only when a trigger file called
151           /tmp/pgsql.trigger.5442 appears, and perform failover according to
152           its content
153
154       ·   remove the trigger file when recovery ends
155
156       ·   remove no-longer-needed files from the archive directory
157
158       On Windows, you might use:
159
160           archive_command = 'copy %p ...\\archive\\%f'
161
162           restore_command = 'pg_standby -d -s 5 -t C:\pgsql.trigger.5442 ...\archive %f %p %r 2>>standby.log'
163
164           recovery_end_command = 'del C:\pgsql.trigger.5442'
165
166       Note that backslashes need to be doubled in the archive_command, but
167       not in the restore_command or recovery_end_command. This will:
168
169       ·   use the copy command to restore WAL files from archive
170
171       ·   produce debugging output in standby.log
172
173       ·   sleep for 5 seconds between checks for next WAL file availability
174
175       ·   stop waiting only when a trigger file called C:\pgsql.trigger.5442
176           appears, and perform failover according to its content
177
178       ·   remove the trigger file when recovery ends
179
180       ·   remove no-longer-needed files from the archive directory
181
182       The copy command on Windows sets the final file size before the file is
183       completely copied, which would ordinarily confuse pg_standby. Therefore
184       pg_standby waits sleeptime seconds once it sees the proper file size.
185       GNUWin32's cp sets the file size only after the file copy is complete.
186
187       Since the Windows example uses copy at both ends, either or both
188       servers might be accessing the archive directory across the network.
189

AUTHOR

191       Simon Riggs <simon@2ndquadrant.com>
192

SEE ALSO

194       pg_archivecleanup(1)
195
196
197
198PostgreSQL 9.2.24                 2017-11-06                     PG_STANDBY(1)
Impressum