Changeset 60

12/09/09 23:09:56 (9 years ago)

looks like done documentation for recovery



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

    r57 r60  
    33=head2 USAGE 
     5/some/path/omnipitr/bin/omnipitr-restore [options] %f %p 
     11=item --data-dir (-D) 
     13Where PostgreSQL datadir is located (path) 
     15=item --source (-s) 
     17Where I<omnipitr-restore> can find wal segments to use. 
     19Check L<Source specification> for more details. 
     21=item --recovery-delay (-w) 
     23Delay when recovering wal segments (in seconds). 
     25This is primarily used to keep window of safety before I<DELETE * FROM 
     26main_table> will be applied on slave database. 
     28=item --finish-trigger (-f) 
     30Name of file to watch for existence - if it exists, recovery process will stop, 
     31and PostgreSQL slave will become fully functional. 
     33Check L<Finishing recovery> section for more details. 
     35=item --remove-unneeded (-r) 
     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. 
     41=item --removal-pause-trigger (-p) 
     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. 
     47=item --log (-l) 
     49Name of logfile (actually template, as it supports %% L<strftime(3)> 
     52=item --verbose (-v) 
     54Log verbosely what is happening. 
    558=head2 DESCRIPTION 
     60Call to I<omnipitr-restore> should be in I<restore_command> variable in 
     63Which options should be given depends only on installation, but generally you 
     64will need at least: 
     68=item * --data-dir 
     70PostgreSQL "%p" passed file path is relative to I<DATADIR>, so it is required to 
     71know it. 
     73=item * --log 
     75to make sure that information is logged someplace about archiving progress 
     77=item * --source 
     79to specify where to load WAL segments from 
     83If you'll specify more than 1 destination, you will also need to specify 
     86Of couse you can provide many --dst-local or many --dst-remote or many mix of 
     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. 
     92Segments will be transferred to destinations in this order: 
     96=item 1. All B<local> destinations, in order provided in command line 
     98=item 2. All B<remote> destinations, in order provided in command line 
     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. 
     107State directory will be cleared after every successfull file send, so it should 
     108stay small in size (expect 1 file of under 500 bytes). 
     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" 
     114=head3 Source specification 
     116If the wal segments are compressed you have to prefix source path with 
     117compression type followed by '%' sign. 
     119Allowed compression types: 
     123=item * gzip 
     125Decompresses with gzip program, used file extension is .gz 
     127=item * bzip2 
     129Decompresses with bzip2 program, used file extension is .bz2 
     131=item * lzma 
     133Decompresses with lzma program, used file extension is .lzma 
     137If you want to pass any extra arguments to compression program, you can either: 
     141=item * make a wrapper 
     143Write a program/script that will be named in the same way your actual 
     144compression program is named, but adding some parameters to call 
     146=item * use environment variables 
     148All of supported compression programs use environment variables: 
     152=item * gzip - GZIP 
     154=item * bzip2 - BZIP2 
     156=item * lzma - XZ_OPT 
     160For details - please consult manual to your choosen compression tool. 
     164=head3 Finishing recovery 
     166There are 2 ways I<omnipitr-restore> can finish recovery, and there are 2 
     167separate ways to signal it that it should finish. 
     169First, the finishing procedures: 
     173=item * smart 
     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. 
     179=item * immediate 
     181In this mode I<omnipitr-restore> will skip all pending WAL segments, and make 
     182PostgreSQL finish recover immediately. 
     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. 
     189Now. I<omnipitr-restore> can be signaled into finishing recovery in 2 ways, one 
     190of which is optional. 
     194=item * trigger file 
     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 
     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. 
     205=item * system signal 
     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. 
     2112 signals are supported: 
     215=item * SIGUSR1 
     217makes the finish I<smart> 
     219=item * SIGUSR2 
     221makes the finish I<immediate> 
    7227=head2 EXAMPLES 
     229=head3 Minimal setup: 
     231    restore_command='/.../omnipitr-restore -D /mnt/data/ -l /var/log/omnipitr/restore.log -s /mnt/wal_restore/ %f %p' 
     233=head3 Minimal setup, but with defined finish trigger and recovery delay (5 
     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' 
     238=head3 Setup as above, but with pause trigger defined for doing backups-on-slave and removing unneeded segments 
     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' 
    9242=head2 COPYRIGHT