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

Revision 101, 8.5 kB (checked in by depesz, 4 years ago)

restore is nearly done. only removal of old files is left to be added

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