Berkeley DB Reference Guide: Environment

Creating an Environment

The DBENV->open function is the standard function for creating or joining a database environment. Transaction-protected or multi-process applications should call DBENV->open before making any other calls to the Berkeley DB library. Applications must obtain an environment handle from the db_env_create function before calling DBENV->open. There are a large number of options that you can set to customize DBENV->open for your environment. These options fall into four broad categories:

Subsystem Initialization:

These flags indicate which Berkeley DB subsystems will be initialized for the environment, and, what operations will happen automatically when databases are accessed within the environment. The flags include DB_JOINENV, DB_INIT_CDB, DB_INIT_LOCK, DB_INIT_LOG, DB_INIT_MPOOL and DB_INIT_TXN. The DB_INIT_CDB flag does initialization for Berkeley DB Concurrent Data Store applications, see Building Berkeley DB Concurrent Data Store applications for more information. The rest of the flags initialize a single subsystem, e.g., when DB_INIT_LOCK is specified, applications reading and writing databases opened in this environment will be using locking to ensure that they do not overwrite each other's changes.

Recovery options:

These flags indicate what recovery is to be performed on the environment before it is opened for normal use, and include DB_RECOVER and DB_RECOVER_FATAL.

Naming options:

These flags modify how file naming happens in the environment, and include DB_USE_ENVIRON and DB_USE_ENVIRON_ROOT.

Miscellaneous:

Finally, there are a number of miscellaneous flags such as DB_CREATE which causes underlying files to be created as necessary. See the DBENV->open manual pages for further information.

Most applications either specify only the DB_INIT_MPOOL flag or they specify all four subsystem initialization flags (DB_INIT_MPOOL, DB_INIT_LOCK, DB_INIT_LOG and DB_INIT_TXN). The former configuration is for applications that simply want to use the basic Access Method interfaces with a shared underlying buffer pool, but don't care about recoverability after application or system failure. The latter is for applications that need recoverability. There are situations where other combinations of the initialization flags make sense, but they are rare.

The DB_RECOVER flag is specified by applications that want to perform any necessary database recovery when they start running, i.e., if there was a system or application failure the last time they ran, they want the databases to be made consistent before they start running again. It is not an error to specify this flag when no recovery needs to be done.

The DB_RECOVER_FATAL flag is more special-purpose. It performs catastrophic database recovery, and normally requires that some initial arrangements be made, i.e., archived log files be brought back into the filesystem. Applications should not normally specify this flag. Instead, under these rare conditions, the db_recover utility should be used.

Copyright Sleepycat Software