### 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 several flags that you can set to customize DBENV->open:

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. Any multi-thread or multi-process use of the environment's databases should specify this flag.

DB_INIT_LOG
  Applications reading and writing databases opened in this environment will be using logging. Any application using transactions should specify this flag.

DB_INIT_MPOOL
  The databases opened in the environment should use a shared underlying memory pool. Any application using access method functionality should specify this flag.

DB_INIT_TXN
  Applications reading and writing databases opened in this environment will be using transactions for recoverability.

DB_LOCKDOWN
  Lock shared Berkeley DB environment files and memory mapped databases into memory.

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 and system environment where it is done. Setting the DB_NOMMAP flag causes Berkeley DB never to map such files into memory. Instead, they are read into the cache using the standard read system calls.

DB_PRIVATE
  Specify that only a single application will access the environment.

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_SYSTEM_MEM
  Create regions in system memory.

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.

Generally, 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 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