m4_comment([$Id: recovery.so,v 10.35 2005/06/16 17:52:20 bostic Exp $])

m4_ref_title(m4_tam Applications,
    Recovery procedures,
    recovery in @transaction protected applications,
    transapp/logfile, transapp/hotfail)

m4_p([dnl
The fifth component of the infrastructure, recovery procedures, concerns
the recoverability of the database.  After any application or system
failure, there are two possible approaches to database recovery:])

m4_nlistbegin

m4_nlist([dnl
There is no need for recoverability, and all databases can be re-created
from scratch.  Although these applications may still need transaction
protection for other reasons, recovery usually consists of removing the
m4_db environment home directory and all files it contains, and then
restarting the application.
Such an application may use the m4_ref(DB_TXN_NOT_DURABLE) flag to avoid
writing log records.])

m4_nlist([dnl
It is necessary to recover information after system or application
failure.  In this case, recovery processing must be performed on any
database environments that were active at the time of the failure.
Recovery processing involves running the m4_ref(db_recover) utility or
calling the m4_refT(dbenv_open) with the m4_ref(DB_RECOVER) or
m4_ref(DB_RECOVER_FATAL) flags.

m4_p([dnl
During recovery processing, all database changes made by aborted or
unfinished transactions are undone, and all database changes made by
committed transactions are redone, as necessary.  Database applications
must not be restarted until recovery completes.  After recovery
finishes, the environment is properly initialized so that applications
may be restarted.])])

m4_nlistend

m4_p([dnl
If performing recovery, there are two types of recovery processing:
m4_italic(normal) and m4_italic(catastrophic).  Which you choose depends
on the source for the database and log files you are using to recover.])

m4_p([dnl
If up-to-the-minute database and log files are accessible on a stable
filesystem, normal recovery is sufficient.  Run the m4_ref(db_recover)
utility or call the m4_refT(dbenv_open) specifying the
m4_ref(DB_RECOVER) flag.  However, the normal recovery case
m4_bold(never) includes recovery using hot backups of the database
environment.  For example, you cannot perform a hot backup of databases
and log files, restore the backup and then run normal recovery -- you
must always run catastrophic recovery when using hot backups.])

m4_p([dnl
If the database or log files have been destroyed or corrupted, or normal
recovery fails, catastrophic recovery is required.  For example,
catastrophic failure includes the case where the disk drive on which
the database or log files are stored has been physically destroyed, or
when the underlying filesystem is corrupted and the operating system's
normal filesystem checking procedures cannot bring that filesystem to
a consistent state.  This is often difficult to detect, and a common
sign of the need for catastrophic recovery is when normal m4_db recovery
procedures fail, or when checksum errors are displayed during normal
database procedures.  When catastrophic recovery is necessary, take the
following steps:])

m4_nlistbegin

m4_nlist([dnl
Restore the most recent snapshots of the database and log files from
the backup media into the directory where recovery will be performed.])

m4_nlist([dnl
If any log files were archived since the last snapshot was made, they
should be restored into the directory where recovery will be performed.

m4_p([dnl
If any log files are available from the database environment that failed
(for example, the disk holding the database files crashed, but the disk
holding the log files is fine), those log files should be copied into
the directory where recovery will be performed.])

m4_p([dnl
Be sure to restore all log files in the order they were written.  The
order is important because it's possible the same log file appears on
multiple backups, and you want to run recovery using the most recent
version of each log file.])

m4_nlist([dnl
Run the m4_ref(db_recover) utility, specifying its m4_option(c) option;
or call the m4_refT(dbenv_open), specifying the m4_ref(DB_RECOVER_FATAL)
flag.  The catastrophic recovery process will review the logs and
database files to bring the environment databases to a consistent state
as of the time of the last uncorrupted log file that is found.  It is
important to realize that only transactions committed before that date
will appear in the databases.])

m4_p([dnl
It is possible to re-create the database in a location different from
the original by specifying appropriate pathnames to the m4_option(h)
option of the m4_ref(db_recover) utility. In order for this to work
properly, it is important that your application refer to files by names
relative to the database home directory or the pathname(s) specified in
calls to m4_ref(dbenv_set_data_dir), instead of using full
pathnames.])])

m4_nlistend

m4_page_footer