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: Environment

# Creating an Environment

The db_appinit function is the standard function for creating or joining a database environment. Every transaction-protected or multi-process application should call db_appinit before making any other calls to the Berkeley DB library.

There are several flags that you can set to customize db_appinit:

DB_CREATE
  Create underlying files as necessary. This flag is normally specified by applications that have the right to create the region and not by those that simply want to join it if it already exists.

DB_INIT_LOCK
  Applications reading and writing databases opened in this environment will be using locking to ensure that they do not overwrite each other's changes.

DB_INIT_LOG
  Applications reading and writing databases opened in this environment will be using logging.

DB_INIT_MPOOL
  The databases opened in the environment should use a shared underlying memory pool.

DB_INIT_TXN
  Applications reading and writing databases opened in this environment may be using transactions.

DB_MPOOL_PRIVATE
  Create a private memory pool, not shared by other processes.

DB_NOMMAP
  Files that are opened read-only in the pool (and that satisfy a few other criteria) are, by default, mapped into the process address space instead of being copied into the local cache. This can enhance performance or degrade it, depending on the architecture where it is done. Setting the DB_NOMMAP flag causes Berkeley DB to never map such files into memory, instead, they are read into the cache using the standard read system calls.

DB_RECOVER
  Run normal recovery on this environment before opening it for normal use. Normal recovery is sufficient to handle most application or system failures.

DB_RECOVER_FATAL
  Run catastrophic recovery on this environment before opening it for normal use. Catastrophic recovery is necessary when restoring a database from an archive.

DB_THREAD
  Ensure that handles returned by the Berkeley DB subsystems are useable by multiple threads within a single process, i.e., that the system is free-threaded.

DB_TXN_NOSYNC
  On transaction commit, do not synchronously flush the log. This means that Berkeley DB will provide atomicity, consistency, and isolation for your transactions, but not durability. Upon recovery, some previously committed transactions may be lost, but your database will be restored to a consistent state.

DB_USE_ENVIRON
  Use environment variables as part of file naming.

DB_USE_ENVIRON_ROOT
  Use environment variables as part of file naming for users with appropriate privileges.

Almost all applications either specify only the DB_INIT_MPOOL flag or they specify all four 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 failure. The latter is for applications that need recoverability. There are situations where other combinations of the initialization flags make sense, but they are quite rare.

The flag DB_RECOVER 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 flag DB_RECOVER_FATAL 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.