Changeset 60

Show
Ignore:
Timestamp:
12/09/09 23:09:56 (9 years ago)
Author:
depesz
Message:

looks like done documentation for recovery

Files:

Legend:

Unmodified
Added
Removed
Modified
Copied
Moved
  • trunk/omnipitr/doc/omnipitr-restore.pod

    r57 r60  
    33=head2 USAGE 
    44 
     5/some/path/omnipitr/bin/omnipitr-restore [options] %f %p 
     6 
     7Options: 
     8 
     9=over 
     10 
     11=item --data-dir (-D) 
     12 
     13Where PostgreSQL datadir is located (path) 
     14 
     15=item --source (-s) 
     16 
     17Where I<omnipitr-restore> can find wal segments to use. 
     18 
     19Check L<Source specification> for more details. 
     20 
     21=item --recovery-delay (-w) 
     22 
     23Delay when recovering wal segments (in seconds). 
     24 
     25This is primarily used to keep window of safety before I<DELETE * FROM 
     26main_table> will be applied on slave database. 
     27 
     28=item --finish-trigger (-f) 
     29 
     30Name of file to watch for existence - if it exists, recovery process will stop, 
     31and PostgreSQL slave will become fully functional. 
     32 
     33Check L<Finishing recovery> section for more details. 
     34 
     35=item --remove-unneeded (-r) 
     36 
     37Makes I<omnipitr-restore> remove unneeded wal segments. These are B<not> 
     38segments that were passed to Pg - I<omnipitr-restore> checks last redo segment 
     39to make sure this is safe. 
     40 
     41=item --removal-pause-trigger (-p) 
     42 
     43Name of file to watch for existence. If it exists - I<omnipitr-restore> will not 
     44remove unneeded wal segments regardless of I<--removal-unneeded> option. This is 
     45to provide a way to make backups on slave. 
     46 
     47=item --log (-l) 
     48 
     49Name of logfile (actually template, as it supports %% L<strftime(3)> 
     50markers 
     51 
     52=item --verbose (-v) 
     53 
     54Log verbosely what is happening. 
     55 
     56=back 
     57 
    558=head2 DESCRIPTION 
    659 
     60Call to I<omnipitr-restore> should be in I<restore_command> variable in 
     61I<recovery.conf>. 
     62 
     63Which options should be given depends only on installation, but generally you 
     64will need at least: 
     65 
     66=over 
     67 
     68=item * --data-dir 
     69 
     70PostgreSQL "%p" passed file path is relative to I<DATADIR>, so it is required to 
     71know it. 
     72 
     73=item * --log 
     74 
     75to make sure that information is logged someplace about archiving progress 
     76 
     77=item * --source 
     78 
     79to specify where to load WAL segments from 
     80 
     81=back 
     82 
     83If you'll specify more than 1 destination, you will also need to specify 
     84I<--state-dir> 
     85 
     86Of couse you can provide many --dst-local or many --dst-remote or many mix of 
     87these. 
     88 
     89Generally omnipitr-restore will try to deliver WAL segment to all destinations, 
     90and will fail if B<any> of them will not accept new segment. 
     91 
     92Segments will be transferred to destinations in this order: 
     93 
     94=over 
     95 
     96=item 1. All B<local> destinations, in order provided in command line 
     97 
     98=item 2. All B<remote> destinations, in order provided in command line 
     99 
     100=back 
     101 
     102In case any destination will fail, I<omnipitr-restore> will save state (which 
     103destinations it delivered the file to) and return error to PostgreSQL - which 
     104will cause PostgrerSQL to call I<omnipitr-restore> again for the same WAL 
     105segment after some time. 
     106 
     107State directory will be cleared after every successfull file send, so it should 
     108stay small in size (expect 1 file of under 500 bytes). 
     109 
     110When constructing command line to put in I<restore_command> PostgreSQL GUC, 
     111please remember that while providing C<"%p" "%f"> will work, I<omnipitr-restore> 
     112requires only "%p" 
     113 
     114=head3 Source specification 
     115 
     116If the wal segments are compressed you have to prefix source path with 
     117compression type followed by '%' sign. 
     118 
     119Allowed compression types: 
     120 
     121=over 
     122 
     123=item * gzip 
     124 
     125Decompresses with gzip program, used file extension is .gz 
     126 
     127=item * bzip2 
     128 
     129Decompresses with bzip2 program, used file extension is .bz2 
     130 
     131=item * lzma 
     132 
     133Decompresses with lzma program, used file extension is .lzma 
     134 
     135=back 
     136 
     137If you want to pass any extra arguments to compression program, you can either: 
     138 
     139=over 
     140 
     141=item * make a wrapper 
     142 
     143Write a program/script that will be named in the same way your actual 
     144compression program is named, but adding some parameters to call 
     145 
     146=item * use environment variables 
     147 
     148All of supported compression programs use environment variables: 
     149 
     150=over 
     151 
     152=item * gzip - GZIP 
     153 
     154=item * bzip2 - BZIP2 
     155 
     156=item * lzma - XZ_OPT 
     157 
     158=back 
     159 
     160For details - please consult manual to your choosen compression tool. 
     161 
     162=back 
     163 
     164=head3 Finishing recovery 
     165 
     166There are 2 ways I<omnipitr-restore> can finish recovery, and there are 2 
     167separate ways to signal it that it should finish. 
     168 
     169First, the finishing procedures: 
     170 
     171=over 
     172 
     173=item * smart 
     174 
     175In this mode I<omnipitr-restore> will feed all available WAL segments to 
     176PostgreSQL (without any I<--recovery-delay> induced delay), and then finish 
     177restoration process. 
     178 
     179=item * immediate 
     180 
     181In this mode I<omnipitr-restore> will skip all pending WAL segments, and make 
     182PostgreSQL finish recover immediately. 
     183 
     184This can be useful in case of running really bad query (think: TRUNCATE users), 
     185and wanting to prevent this change to be replicated to slave. 
     186 
     187=back 
     188 
     189Now. I<omnipitr-restore> can be signaled into finishing recovery in 2 ways, one 
     190of which is optional. 
     191 
     192=over 
     193 
     194=item * trigger file 
     195 
     196This one is optional. If you will use --finish-trigger switch, 
     197I<omnipitr-restore> will look for this file, and if it exists - it will start 
     198finishing. 
     199 
     200If the file exists, and contains string "NOW" (without quotation characters, but 
     201with optional new line character "\n"), I<omnipitr-restore> will enter 
     202"immediate finish" procedure. If the content is different, or the file is empty 
     203- it will proceed in smart finish mode. 
     204 
     205=item * system signal 
     206 
     207This one works always, regardless of --finish-trigger switch. Generally you can 
     208send system signals (kill) to I<omnipitr-restore> to make it go to finish 
     209recovery procedure. 
     210 
     2112 signals are supported: 
     212 
     213=over 
     214 
     215=item * SIGUSR1 
     216 
     217makes the finish I<smart> 
     218 
     219=item * SIGUSR2 
     220 
     221makes the finish I<immediate> 
     222 
     223=back 
     224 
     225=back 
     226 
    7227=head2 EXAMPLES 
    8228 
     229=head3 Minimal setup: 
     230 
     231    restore_command='/.../omnipitr-restore -D /mnt/data/ -l /var/log/omnipitr/restore.log -s /mnt/wal_restore/ %f %p' 
     232 
     233=head3 Minimal setup, but with defined finish trigger and recovery delay (5 
     234mintues): 
     235 
     236    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' 
     237 
     238=head3 Setup as above, but with pause trigger defined for doing backups-on-slave and removing unneeded segments 
     239 
     240    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' 
     241 
    9242=head2 COPYRIGHT 
    10243