root/trunk/omnipitr/doc/omnipitr-restore.pod

Revision 132, 9.1 kB (checked in by depesz, 4 years ago)

add information about lack of delay in initial recovery

Line 
1 =head1 OmniPITR - omnipitr-restore
2
3 =head2 USAGE
4
5 /some/path/omnipitr/bin/omnipitr-restore [options] %f %p
6
7 Options:
8
9 =over
10
11 =item --data-dir (-D)
12
13 Where PostgreSQL datadir is located (path) (defaults to current working
14 directory).
15
16 =item --source (-s)
17
18 Where I<omnipitr-restore> can find wal segments to use.
19
20 Check L<Source specification> for more details.
21
22 =item --recovery-delay (-w)
23
24 Delay when recovering wal segments (in seconds).
25
26 This is primarily used to keep window of safety before I<DELETE * FROM
27 main_table> will be applied on slave database.
28
29 This delay does not apply to initial recovery (getting system from backup till
30 "Minimum recovery ending location"). Reason for this is simple - before reaching
31 minimum recovery ending location database can be in nonconsistent state. So
32 there is no point in stalling till we get to point where database is consistent.
33
34 =item --finish-trigger (-f)
35
36 Name of file to watch for existence - if it exists, recovery process will stop,
37 and PostgreSQL slave will become fully functional.
38
39 Check L<Finishing recovery> section for more details.
40
41 =item --remove-unneeded (-r)
42
43 Makes I<omnipitr-restore> remove unneeded wal segments. These are B<not>
44 segments that were passed to Pg - I<omnipitr-restore> checks last redo segment
45 to make sure this is safe.
46
47 =item --remove-at-a-time (-rt)
48
49 When removing old segments, remove at most that many segments before re-entering
50 loop to check for signals and/or new segment availability for Postgres.
51
52 Defaults to 3.
53
54 =item --removal-pause-trigger (-p)
55
56 Name of file to watch for existence. If it exists - I<omnipitr-restore> will not
57 remove unneeded wal segments regardless of I<--removal-unneeded> option. This is
58 to provide a way to make backups on slave.
59
60 =item --pre-removal-processing (-h)
61
62 If given, argument will be treated as shell command to run when any segment will
63 be removed from archive.
64
65 If the hook will finish without errors - segment will be removed. If there will
66 be errors - removal procedure will be postponed, and after some time, it will be
67 retried.
68
69 There will be one extra parameter attached, which will be name of the segment
70 file to be processed (prepared in such a way that it will be relative to current
71 working directory).
72
73 Passed segment will always be uncompressed.
74
75 =item --temp-dir (-t)
76
77 Where to create temporary files (defaults to /tmp or I<$TMPDIR> environment
78 variable location). This is only used when using pre-removal-processing.
79
80 =item --log (-l)
81
82 Name of logfile (actually template, as it supports %% L<strftime(3)>
83 markers. Unfortunately due to the %x usage by PostgreSQL, We cannot use %%
84 macros directly. Instead - any occurence of ^ character in log dir will be first
85 changed to %, and later on passed to strftime.
86
87 =item --pid-file
88
89 Name of file to use for pidfile. If it is specified, than only one copy of
90 I<omnipitr-restore> (with this pidfile) can run at the same time.
91
92 Trying to run second copy of I<omnipitr-restore> will result in an error.
93
94 =item --verbose (-v)
95
96 Log verbosely what is happening.
97
98 =item --gzip-path (-gp)
99
100 Full path to gzip program - in case you can't set proper PATH environment
101 variable.
102
103 =item --bzip2-path (-bp)
104
105 Full path to bzip2 program - in case you can't set proper PATH environment
106 variable.
107
108 =item --lzma-path (-lp)
109
110 Full path to lzma program - in case you can't set proper PATH environment
111 variable.
112
113 =item --pgcontroldata-path (-pp)
114
115 Full path to pg_controldata program - in case you can't set proper PATH
116 environment variable.
117
118 =back
119
120 =head2 DESCRIPTION
121
122 Call to I<omnipitr-restore> should be in I<restore_command> variable in
123 I<recovery.conf>.
124
125 Which options should be given depends only on installation, but generally you
126 will need at least:
127
128 =over
129
130 =item * --data-dir
131
132 PostgreSQL "%p" passed file path is relative to I<DATADIR>, so it is required to
133 know it.
134
135 =item * --log
136
137 to make sure that information is logged someplace about archiving progress
138
139 =item * --source
140
141 to specify where to load WAL segments from
142
143 =back
144
145 If you'll specify more than 1 destination, you will also need to specify
146 I<--state-dir>
147
148 Of couse you can provide many --dst-local or many --dst-remote or many mix of
149 these.
150
151 Generally omnipitr-restore will try to deliver WAL segment to all destinations,
152 and will fail if B<any> of them will not accept new segment.
153
154 Segments will be transferred to destinations in this order:
155
156 =over
157
158 =item 1. All B<local> destinations, in order provided in command line
159
160 =item 2. All B<remote> destinations, in order provided in command line
161
162 =back
163
164 In case any destination will fail, I<omnipitr-restore> will save state (which
165 destinations it delivered the file to) and return error to PostgreSQL - which
166 will cause PostgrerSQL to call I<omnipitr-restore> again for the same WAL
167 segment after some time.
168
169 State directory will be cleared after every successfull file send, so it should
170 stay small in size (expect 1 file of under 500 bytes).
171
172 When constructing command line to put in I<restore_command> PostgreSQL GUC,
173 please remember that while providing C<"%p" "%f"> will work, I<omnipitr-restore>
174 requires only "%p"
175
176 =head3 Source specification
177
178 If the wal segments are compressed you have to prefix source path with
179 compression type followed by '=' sign.
180
181 Allowed compression types:
182
183 =over
184
185 =item * gzip
186
187 Decompresses with gzip program, used file extension is .gz
188
189 =item * bzip2
190
191 Decompresses with bzip2 program, used file extension is .bz2
192
193 =item * lzma
194
195 Decompresses with lzma program, used file extension is .lzma
196
197 =back
198
199 If you want to pass any extra arguments to compression program, you can either:
200
201 =over
202
203 =item * make a wrapper
204
205 Write a program/script that will be named in the same way your actual
206 compression program is named, but adding some parameters to call
207
208 =item * use environment variables
209
210 All of supported compression programs use environment variables:
211
212 =over
213
214 =item * gzip - GZIP
215
216 =item * bzip2 - BZIP2
217
218 =item * lzma - XZ_OPT
219
220 =back
221
222 For details - please consult manual to your choosen compression tool.
223
224 =back
225
226 =head3 Finishing recovery
227
228 There are 2 ways I<omnipitr-restore> can finish recovery, and there are 2
229 separate ways to signal it that it should finish.
230
231 First, the finishing procedures:
232
233 =over
234
235 =item * smart
236
237 In this mode I<omnipitr-restore> will feed all available WAL segments to
238 PostgreSQL (without any I<--recovery-delay> induced delay), and then finish
239 restoration process.
240
241 =item * immediate
242
243 In this mode I<omnipitr-restore> will skip all pending WAL segments, and make
244 PostgreSQL finish recover immediately.
245
246 This can be useful in case of running really bad query (think: TRUNCATE users),
247 and wanting to prevent this change to be replicated to slave.
248
249 =back
250
251 Now. I<omnipitr-restore> can be signaled into finishing recovery in 2 ways, one
252 of which is optional.
253
254 =over
255
256 =item * trigger file
257
258 This one is optional. If you will use --finish-trigger switch,
259 I<omnipitr-restore> will look for this file, and if it exists - it will start
260 finishing.
261
262 If the file exists, and contains string "NOW" (without quotation characters, but
263 with optional new line character "\n"), I<omnipitr-restore> will enter
264 "immediate finish" procedure. If the content is different, or the file is empty
265 - it will proceed in smart finish mode.
266
267 =item * system signal
268
269 This one works always, regardless of --finish-trigger switch. Generally you can
270 send system signals (kill) to I<omnipitr-restore> to make it go to finish
271 recovery procedure.
272
273 Only 1 signals are supported:
274
275 =over
276
277 =item * SIGUSR1
278
279 makes the finish I<immediate>
280
281 =back
282
283 It is currently not possible to forcing 'smart' finishing by signal, due to
284 the fact that L<omnipitr-restore> is restarted after every segment.
285
286 =back
287
288 =head3 Segment removal
289
290 omnipitr-restore will automatically remove segments that are no longer
291 necessary.
292
293 To make it happen, it will periodically run I<pg_controldata> program, and check
294 name of last segment required for redo.
295
296 If pre-removal-processing is defined, it will be called before actuall removal.
297
298 omnipitr-restore will remove segments chronologically - oldest segments first.
299
300 One useful idea for pre-removal-processing, is using L<omnipitr-archive> for
301 processing - to send xlog segments to some permanent storage place.
302
303 =head2 EXAMPLES
304
305 =head3 Minimal setup:
306
307     restore_command='/.../omnipitr-restore -l /var/log/omnipitr/restore.log -s /mnt/wal_restore/ %f %p'
308
309 =head3 Minimal setup, but with defined finish trigger and recovery delay (5
310 mintues):
311
312     restore_command='/.../omnipitr-restore -D /mnt/data/ -l /var/log/omnipitr/restore.log -s /mnt/wal_restore/ -w 300 -f /tmp/finish.trigger %f %p'
313
314 =head3 Setup as above, but with pause trigger defined for doing backups-on-slave and removing unneeded segments
315
316     restore_command='/.../omnipitr-restore -D /mnt/data/ -l /var/log/omnipitr/restore.log -s /mnt/wal_restore/ -w 300 -f /tmp/finish.trigger -r -p /tmp/pause.trigger %f %p'
317
318 =head3 Minimal setup, but with backing up segments to remote server:
319
320     restore_command='/.../omnipitr-restore -l /var/log/omnipitr/restore.log -s /mnt/wal_restore/ -h "/.../omnipitr-archive --force-data-dir -l /var/log/omnipitr/archive.log -dr bzip2=rsync://backup/postgres/xlogs/" %f %p'
321
322 =head2 COPYRIGHT
323
324 The OmniPITR project is Copyright (c) 2009 OmniTI. All rights reserved.
325
Note: See TracBrowser for help on using the browser.