Creating a database environment

The Berkeley DB environment is created and described by the db_env_create() and DB_ENV->open() interfaces. In situations where customization is desired, such as storing log files on a separate disk drive or selection of a particular cache size, applications must describe the customization by either creating an environment configuration file in the environment home directory or by arguments passed to other DB_ENV handle methods.

Once an environment has been created, database files specified using relative pathnames will be named relative to the home directory. Using pathnames relative to the home directory allows the entire environment to be easily moved, simplifying restoration and recovery of a database in a different directory or on a different system.

Applications first obtain an environment handle using the db_env_create() method, then call the DB_ENV->open() method which creates or joins the database environment. There are a number of options you can set to customize DB_ENV->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_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 Concurrent Data Store introduction for more information.) The rest of the flags initialize a single subsystem; that is, 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, which include DB_RECOVER and DB_RECOVER_FATAL, indicate what recovery is to be performed on the environment before it is opened for normal use.

Naming options:

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

Miscellaneous:

Finally, there are a number of miscellaneous flags, for example, DB_CREATE which causes underlying files to be created as necessary. See the DB_ENV->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 in which 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. That is, 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; that is, 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.

The following is a simple example of a function that opens a database environment for a transactional program.

DB_ENV *
db_setup(char *home, char *data_dir, FILE *errfp, char *progname)
    {
    DB_ENV *dbenv;
    int ret;
    /*
     * Create an environment and initialize it for additional error
     * reporting.
     */
    if ((ret = db_env_create(&dbenv, 0)) != 0) {
        fprintf(errfp, "%s: %s\n", progname, db_strerror(ret));
        return (NULL);
    }
    dbenv->set_errfile(dbenv, errfp);
    dbenv->set_errpfx(dbenv, progname);
    /*
     * Specify the shared memory buffer pool cachesize: 5MB.
     * Databases are in a subdirectory of the environment home.
     */
    if ((ret = dbenv->set_cachesize(dbenv, 0, 
                                     5 * 1024 * 1024, 0)) != 0) {
        dbenv->err(dbenv, ret, "set_cachesize");
        goto err;
    }
    if ((ret = dbenv->add_data_dir(dbenv, data_dir)) != 0) {
        dbenv->err(dbenv, ret, "add_data_dir: %s", data_dir);
        goto err;
    }
    /* Open the environment with full transactional support. */
    if ((ret = dbenv->open(dbenv, home, DB_CREATE | DB_INIT_LOG | 
                DB_INIT_LOCK | DB_INIT_MPOOL | 
                DB_INIT_TXN, 0)) != 0) {
        dbenv->err(dbenv, ret, "environment open: %s", home);
        goto err;
    }
    return (dbenv);
err:    (void)dbenv->close(dbenv, 0);
    return (NULL);
}