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.
