db_recover



NAME

       db_recover - the DB database recovery utility


SYNOPSIS

       db_recover [-cv] [-h home]


DESCRIPTION

       The  db_recover  utility  must  be run after an unexpected
       application, DB, or system failure to restore the database
       to  a  consistent  state.   All committed transactions are
       guaranteed to appear after db_recover  has  run,  and  all
       uncommitted transactions will be completely undone.

       The options are as follows:

       -c   Failure was catastrophic.

       -h   Specify a home directory for the database.

       -v   Run in verbose mode.

       In  the  case  of  catastrophic failure, a snapshot of all
       database files must be restored along with all of the  log
       files  written  since the database file snapshot was made.
       (If disk space is a problem, log files may  be  referenced
       by  symbolic links).  If the failure was not catastrophic,
       the files present on the system at the time of failure are
       sufficient to perform recovery.

       If  log  files  are  missing, db_recover will identify the
       missing log file and fail, in which case the  missing  log
       files need to be restored and recovery performed again.

       Filesystem  operations,  e.g.,  file creation, deletion or
       renaming, cannot be transaction protected,  and  therefore
       db_recover  cannot  re-create,  delete  or rename files as
       part of recovery.  If db_recover cannot  find  a  database
       file  referenced in the log, it will output a warning mes-
       sage that it was unable to locate a file  it  expected  to
       find.   This  message  is  only a warning, as the file may
       have subsequently been deleted as part of normal  database
       operations  before  the  failure occurred.  Database files
       created since the last database snapshot, and not  deleted
       before  the  failure,  must  be  manually  created  (using
       db_open(3)), before db_recover is run.

       Generally, it's simplest to do  filesystem  operations  at
       the  same  time as a snapshot of the database is made.  To
       perform filesystem operations:

              1.   Shutdown all database operations.
              2.   Rename, create or delete files.
              3.   Make a snapshot of the database.
              4.   Restart database applications.

       The  db_recover  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_recover  to  clean up after itself and exit,
       send it an interrupt signal (SIGINT).

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


RECOVERY

       After an application or system failure, there are two pos-
       sible approaches to database recovery.   If  there  is  no
       need to retain state across the failure, and all databases
       can be started anew, the database home directory can  sim-
       ply  be  removed  and  recreated.   If  it is necessary to
       retain  persistent  state  across   failures,   then   the
       db_recover(1)  utility  should be run for each DB applica-
       tion environment, i.e., each database home directory.

       The db_recover utility will remove all the shared  regions
       (which  may have been corrupted by the failure), establish
       the end of the log by identifying the last record  written
       to   the  log,  and  then  perform  transaction  recovery.
       Database applications must not be restarted until recovery
       completes.   During transaction recovery, all changes made
       by aborted transactions are undone and all changes made by
       committed  transactions  are  redone, as necessary.  After
       recovery runs, the environment is properly initialized  so
       that  applications may be restarted.  Any time an applica-
       tion crashes or the system fails, db_recover should be run
       on any exiting database environments.

       Additionally,  there  are  two  forms  of recovery: normal
       recovery  and  catastrophic  recovery.   The  DB   package
       defines  catastrophic  failure  to be failure where either
       the database or log files have been destroyed or corrupted
       from  the  point  of view of the filesystem.  For example,
       catastrophic failure includes  the  case  where  the  disk
       drive  on which either the database or logs are stored has
       crashed, or when filesystem recovery is  unable  to  bring
       the  database  and  log  files  to a consistent state with
       respect to the filesystem.  If the failure  is  non-catas-
       trophic,  i.e.,  the database files and log are accessible
       on a filesystem that  has  recovered  cleanly,  db_recover
       will review the logs and database files to ensure that all
       committed transactions appear  and  that  all  uncommitted
       transactions  are undone.  If the failure is catastrophic,
       a snapshot of the database  files  and  the  archived  log
       files  must  be restored onto the system.  Then db_recover
       will review the logs  and  database  files  to  bring  the
       database  to a consistent state as of the date of the last
       archived log file.   Only  transactions  committed  before
       that date will appear in the database.  See db_archive (1)
       for specific information about  archiving  and  recovering
       databases after catastrophic failure.



ENVIRONMENT VARIABLES

       The  following  environment variables affect the execution
       of db_recover:

       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).


BUGS

       Future versions of DB are expected to remove the  restric-
       tion  that  database files must be manually created before
       recovery is performed.


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)