Berkeley DB Reference Guide: Environment

File naming

The most important task of the environment is to structure file naming within Berkeley DB.

Each of the locking, logging, memory pool and transaction subsystems of Berkeley DB require shared memory regions, backed by the filesystem. Further, cooperating applications (or multiple invocations of the same application) must agree on the location of the shared memory regions and other files used by the Berkeley DB subsystems, the log files used by the logging subsystem, and, of course, the data files. Although it is possible to specify full pathnames to all Berkeley DB functions, this is cumbersome and requires that applications be recompiled when database files are moved.

Applications are normally expected to specify a single directory home for their database. This can be done easily in the call to DBENV->open by specifying a value for the db_home argument. There are more complex configurations where it may be desirable to override db_home or provide supplementary path information.

Specifying file naming to Berkeley DB

The following describes the possible ways in which file naming information may be specified to the Berkeley DB library. The specific circumstances and order in which these ways are applied are described in a subsequent paragraph.

db_home

If the db_home argument to DBENV->open is non-NULL, its value may be used as the database home, and files named relative to its path.

DB_HOME

If the DB_HOME environment variable is set when DBENV->open is called, its value may be used as the database home, and files named relative to its path.

The DB_HOME environment variable is intended to permit users and system administrators to override application and installation defaults, e.g.:

env DB_HOME=/database/my_home application

Application writers are encouraged to support the -h option found in the supporting Berkeley DB utilities to let users specify a database home.

DB_ENV methods

There are three DB_ENV methods that affect file naming. The DBENV->set_data_dir function specifies a directory to search for database files. The DBENV->set_lg_dir function specifies a directory in which to create logging files. The DBENV->set_tmp_dir function specifies a directory in which to create backing temporary files. These methods are intended to permit applications to customize file location for a database. For example, an application writer can place data files and log files in different directories, or instantiate a new log directory each time the application runs.

DB_CONFIG

The same information specified to the above DB_ENV methods may also be specified using a configuration file. If an environment home directory has been specified (either by the application specifying a non-NULL db_home argument to DBENV->open, or by the application setting the DB_USE_ENVIRON or DB_USE_ENVIRON_ROOT flags and the DB_HOME environment variable being set), any file named DB_CONFIG in the database home directory will be read for lines of the format NAME VALUE.

The characters delimiting the two parts of the entry may be one or more whitespace characters, and trailing whitespace characters are discarded. All empty lines or lines whose first character is a whitespace or hash (#) character will be ignored. Each line must specify both the NAME and the VALUE of the pair. The specific NAME VALUE pairs are documented in the manual DBENV->set_data_dir, DBENV->set_lg_dir and DBENV->set_tmp_dir pages.

The DB_CONFIG configuration file is intended to permit systems to customize file location for an environment independent of applications using that database. For example, a database administrator can move the database log and data files to a different location without application recompilation.

File name resolution in Berkeley DB

The following describes the specific circumstances and order in which the different ways of specifying file naming information are applied. Berkeley DB file name processing proceeds sequentially through the following steps:

absolute pathnames

If the file name specified to a Berkeley DB function is an absolute pathname, that file name is used without modification by Berkeley DB.

On UNIX systems, an absolute pathname is defined as any pathname that begins with a leading slash (/).

On Windows systems, an absolute pathname is any pathname that begins with a leading slash or leading backslash (\), or any pathname beginning with a single alphabetic character, a colon and a leading slash or backslash, e.g., C:/tmp.

DB_ENV methods, DB_CONFIG

If a relevant configuration string (e.g., set_data_dir), is specified either by calling a DB_ENV method or as a line in the DB_CONFIG configuration file, the VALUE from the NAME VALUE pair is prepended to the current file name. If the resulting file name is an absolute pathname, the file name is used without further modification by Berkeley DB.

db_home

If the application specified a non-NULL db_home argument to DBENV->open its value is prepended to the current file name. If the resulting file name is an absolute pathname, the file name is used without further modification by Berkeley DB.

DB_HOME

If the db_home argument is null, the DB_HOME environment variable was set and the application has set the appropriate DB_USE_ENVIRON or DB_USE_ENVIRON_ROOT environment variable, its value is prepended to the current file name. If the resulting file name is an absolute pathname, the file name is used without further modification by Berkeley DB.

(nothing)

Finally, all file names are interpreted relative to the current working directory of the process.

The common model for a Berkeley DB environment is one where only the DB_HOME environment variable, or the db_home argument, is specified. In this case, all data file names are relative to that directory, and all files created by the Berkeley DB subsystems will be created in that directory.

The more complex model for a transaction environment might be one where a database home is specified, using either the DB_HOME environment variable or the db_home argument to DBENV->open, and then the data directory and logging directory are set to the relative path names of directories underneath the environment home.

Examples

DBENV->open(DBENV, "/a/database", ...);

DBENV->set_tmp_dir(DBENV, "/b/temporary");
DBENV->open(DBENV, "/a/database", ...);

DBENV->set_lg_dir("logdir");
DBENV->set_data_dir("datadir");
DBENV->open(DBENV, "/a/database", ...);

Store data files in /a/database/data1 and /b/data2, and all other files in the directory /a/database. Any data files that are created will be created in /b/data2, because it is the first DB_DATA_DIR directory specified:

DBENV->set_data_dir(DBENV, "/b/data2");
DBENV->set_data_dir(DBENV, "data1");
DBENV->open(DBENV, "/a/database", ...);

Copyright Sleepycat Software