db_archive



NAME

       db_archive - the DB database archiver


SYNOPSIS

       db_archive [-alsv] [-h home]


DESCRIPTION

       The  db_archive utility writes the pathnames of log files,
       which are no longer involved in  active  transactions,  to
       the  standard  output,  one  pathname per line.  These log
       files should be written to backup  media  to  provide  for
       recovery  in  the case of catastrophic failure (which also
       requires a snapshot of the database files), but  they  may
       then be deleted from the system to reclaim disk space.

       The options are as follows:

       -a   Write all pathnames as absolute pathnames, instead of
            relative to the database home directories.

       -h   Specify a home directory for the database.

       -l   Write out the pathnames of all of  the  database  log
            files,  whether  or  not  they are involved in active
            transactions.

       -s   Write the pathnames of all of the database files that
            need  to be archived in order to recover the database
            from catastrophic failure.

            It is possible that some of the files  referenced  in
            the  log have since been deleted from the system.  In
            this  case,  db_archive  will  ignore   them.    When
            db_recover(1) is run, any files referenced in the log
            that are not present during recovery are  assumed  to
            have been deleted and will not be recovered.

       -v   Run  in  verbose mode, listing the checkpoints in the
            log files as they are reviewed.

       The  db_archive  utility  attaches  to  DB  shared  memory
       regions.   In  order to avoid region corruption, it should
       always be given the chance to detach and exit  gracefully.
       To  cause  db_archive  to  clean up after itself and exit,
       send it an interrupt signal (SIGINT).

       The db_archive utility exits 0 on success, and  >0  if  an
       error occurs.


DB ARCHIVAL PROCEDURES

       There  are  two aspects to managing the recoverability and
       disk consumption of your DB  databases.   First,  you  may
       want to periodically create snapshots of your databases to
       make  it  possible  to  recover  them  from   catastrophic
       failure.   Second,  you'll want to periodically remove log
       files in order to conserve on disk space.

       To create a snapshot of your database that can be used  to
       recover  from  catastrophic  failure,  the following steps
       should be taken:

       1.   Run db_archive -s to identify  all  of  the  database
            data  files  that  must  be saved, and copy them to a
            backup device, (e.g., tape).

       2.   If your database is currently active, i.e.,  you  are
            reading  and  writing to the database files while the
            snapshot is being taken, run db_archive -l  to  iden-
            tify  the  database  log  files,  and  copy them to a
            backup device, (e.g., tape).   If  the  database  log
            files  are  stored  in  a separate directory from the
            other database files, it may be  simpler  to  archive
            the directory itself instead of the individual files.

       Note that the order of these operations is important,  and
       that  the  database  files must be archived before the log
       files.

       The DB library supports on-line backups,  and  it  is  not
       necessary to stop reading or writing your databases during
       the time when you create  this  snapshot.   Note  however,
       that the snapshot of an active database will be consistent
       as of some unspecified  time  between  the  start  of  the
       archival  and  when  archival  is  completed.  To create a
       snapshot as of a specific time, you must stop reading  and
       writing   your  databases  for  the  entire  time  of  the
       archival, in which case the log files do not  need  to  be
       archived.

       Once  these  steps  are  completed,  your  database can be
       recovered from catastrophic failure to its state as of the
       time  the  archival  was done.  To update your snapshot so
       that recovery from catastrophic failure is possible up  to
       a  new point in time, repeat step #2, copying all existing
       log files to a backup device.

       Each time that a  complete  snapshot  is  made,  i.e.  all
       database data files are copied to a backup device, you can
       discard all previous snapshots and saved log files.

       The time to restore from catastrophic failure is  a  func-
       tion  of  the number of log records that have been written
       since the snapshot was originally created.   Perhaps  more
       importantly,  the more separate pieces of backup media you
       use, the more likely that you will have a problem  reading
       one  of them.  For these reasons, it is often best to make
       snapshots on a regular basis.

       For archival safety remember to ensure that you have  mul-
       tiple  copies  of  your  database backups, that you verify
       that your archival media is error-free, and that copies of
       your backups are stored off-site!

       To  restore  your database after catastrophic failure, the
       following steps should be taken:

       1.   Restore the copies of the  database  files  from  the
            backup media.

       2.   Restore  the  copies of the log files from the backup
            media, in the  order  in  which  they  were  written.
            (It's possible that the same log file appears on mul-
            tiple backups, and you only want the most recent ver-
            sion of that log file!)

       3.   Run db_recover -c to recover the database.

       It is possible to recreate the database in a location dif-
       ferent than the original, by specifying appropriate  path-
       names to the -h option of the db_recover utility.

       To  conserve disk space by removing log files, the follow-
       ing steps should be taken:

       1.   Run db_archive to identify all of the log files  that
            are no longer involved in an active transaction.

       2.   If  you are concerned with catastrophic failure, copy
            them to a backup device, (e.g., tape)  as  they  will
            have  to  be restored as part of recovery from catas-
            trophic failure.

       3.   Remove the log files from the system.


ENVIRONMENT VARIABLES

       The following environment variables affect  the  execution
       of db_archive:

       DB_HOME
            If the -h option is not specified and the environment
            variable DB_HOME is set, it is used as  the  path  of
            the database home, as described in db_appinit(3).


SEE ALSO

       The  DB  library  is  a family of groups of functions that
       provides a modular programming interface  to  transactions
       and  record-oriented  file  access.   The library includes
       support for transactions, locking, logging and  file  page
       caching,  as well as various indexed access methods.  Many
       of the functional groups  (e.g.,  the  file  page  caching
       functions)  are  useful  independent of the other DB func-
       tions, although  some  functional  groups  are  explicitly
       based  on  other functional groups (e.g., transactions and
       logging).  For a general description of  the  DB  package,
       see  db(3).   For a description of the access methods, see
       db_open(3).  For a description of  cursors  within  access
       methods,  see  db_cursor(3);  transactions, see db_txn(3);
       the lock manager, see db_lock(3);  the  log  manager,  see
       db_log(3);  the memory pool manager, see db_mpool(3).  For
       information on configuring the DB  transaction  processing
       environment,  and DB support utilities, see db_appinit(3),
       db_archive(1),   db_checkpoint(1),   db_deadlock(1)    and
       db_recover(1).   For  information on dumping and reloading
       DB databases, see db_dump(1) and db_load(1).

       db_archive(1), db_checkpoint(1), db_deadlock(1), db_dump(1),
       db_load(1), db_recover(1), db(3), db_appinit(3), db_cursor(3),
       db_dbm(3), db_lock(3), db_log(3), db_mpool(3), db_open(3),
       db_txn(3)