Description: Berkeley DB: An embedded database programmatic toolkit.
Keywords: embedded,database,programmatic,toolkit,b+tree,btr ee,hash,hashing,transaction,transactions,locking,logging,access method,access me thods,java,C,C++

### Berkeley DB Reference Guide: Architecture

# Environment

The Berkeley DB environment is the encapsulation of the five Berkeley DB subsystems, a collection of related applications, and the databases accessed by those applications. The applications we will be describing here are similar to the Access Method applications previously described in the Reference Guide, but they are also fully recoverable in the face of application or system failure. The Berkeley DB application environment is created and described by the db_appinit interface. This interface creates a consistent naming scheme for all of the subsystems sharing the environment.

It is important to realize that all applications sharing a single home directory implicitly trust each other. They have access to each other's data as it resides in the shared memory buffer pool and will share resources such as buffer space and locks. At the same time, any applications that access the same files must share an environment if consistency is to be maintained across the different applications.

The simplest way to administer a Berkeley DB application environment is to create a single home directory that stores the files for the applications that will share the environment. The environment can then be identified by the name of that directory. The environment may be shared by any number of applications as well as by any number of threads within the applications.

Note that it is possible for an environment to include resources from other directories on the system, and applications often choose to distribute resources to other directories or disks for performance or other reasons. However, by default, the shared memory regions (i.e., the locking, logging, memory pool, and transaction regions) and log files will be stored in the specified directory hierarchy. In situations where further customization is desired, such as placing the log files on a separate device, it is recommended that the application installation process create a configuration file named DB_CONFIG in the database home directory, specifying the customization. See db_appinit for details on this procedure.

Once an environment has been created, database files specified using relative pathnames will be named relative to the home directory. When recovery needs to be run (e.g., after system or application failure), this directory is specified as the home directory to db_recover and the system is restored to a consistent state, ready for the applications to be restarted. Note that the use of pathnames relative to the home directory is encouraged, so that the entire environment can be moved to facilitate restoring and recovering a database in a different directory or even on a different system.

When transactions have been configured for the environment, the checkpoint daemon, db_checkpoint, must be run as long as there are applications present. When locking is being used, the deadlock detection daemon, db_deadlock, must be run as long as there are applications present. The db_archive utility provides information to facilitate log reclamation and creation of database snapshots. After application or system failure, the db_recover, utility must be run before any applications are restarted to return the database to a consistent state.

Finally, Berkeley DB applications that run with additional privileges should always call the db_appinit function to initialize naming for their application. This ensures that the environment variables DB_HOME and TMPDIR will be used only if the application explicitly specifies that they are safe.