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

Revision 91, 7.8 kB (checked in by depesz, 4 years ago)

change the strftime % marker to - also to avoid clash with postgresql % usage

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