# db_recover

           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, an archival copy, or
           ``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).   For  further
           information on creating  a  database  snapshot,  see  ``DB
           ARCHIVAL PROCEDURES'' in db_archive(1).

           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(s) and fail, in which  case  the  missing
           log  files  need  to  be  restored  and recovery performed
           again.

           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.

## FILESYSTEM OPERATIONS

           Filesystem   operations,   e.g.,   moving   the   database
           environment to  a  different  machine  or  file  creation,
           deletion  or  renaming,  cannot  be transaction protected.
           For this reason, 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  message  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.  Note that committed  transactions  that
           involved  these  missing  files  are  rolled forward, even
           though the files were not found.  If the  files  were  not
           intentionally  deleted  (e.g., they were created after the
           last database snapshot, but were lost during  a  failure),
           they  must  be  manually  created  (using db_open(3)), and
           db_recover must be rerun.

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

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

           To cleanly shutdown database operations, all  applications
           accessing  the  database environment must be shutdown.  If
           the applications are not implemented such that they can be
           shutdown  gracefully  (i.e., closing all references to the
           database environment), db_recover must be  run  after  all
           applications   have   been   killed  to  ensure  that  the
           underlying database is consistent and flushed to disk.

## RECOVERY

           After an application or  system  failure,  there  are  two
           possible  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
           simply 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
           application   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
           application 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-
           catastrophic,   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
           restriction  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
           functions,  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_intro(3).

           db_archive(1), db_checkpoint(1), db_deadlock(1), db_dump(1),
           db_load(1), db_recover(1), db_stat(1), db_intro(3),
           db_appinit(3), db_cursor(3), db_dbm(3), db_internal(3),
           db_lock(3), db_log(3), db_mpool(3), db_open(3), db_thread(3),
           db_txn(3)