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, 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 infor-
mation 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 per-
form 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 environ-
ment to a different machine or file creation, deletion or
renaming, cannot be transaction protected. For this rea-
son, 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 underly-
ing database is consistent and flushed to disk.
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_intro(3).
db_archive(1), db_checkpoint(1), db_deadlock(1), db_dump(1),
db_intro(3), db_load(1), db_recover(1), db_stat(1),
db_appinit(3), db_cursor(3), db_dbm(3), db_lock(3), db_log(3),
db_mpool(3), db_open(3), db_txn(3)