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

Revision 103, 8.7 kB (checked in by depesz, 4 years ago)

work in progress. no docs, has to pass tests, but code looks like done

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