- 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