Enter your search terms

GNU-Darwin Web Submit search form

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. The db_appinit function makes it possible to place database files in a single directory, or in multiple directories, grouped by their function within the database.

Applications are normally expected to specify a single directory home for their database. This can be done easily in the call to db_appinit 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.

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 db_appinit 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 db_appinit is called, its value may be used as the database home, and files named relative to its path.

db_config

The db_config argument to db_appinit may be used to specify an array of character strings of the format NAME VALUE, that specify file name information for the Berkeley DB process' environment.

The characters delimiting the two parts of the entry may be one or more whitespace characters, and trailing whitespace characters are discarded. Each entry must specify both the NAME and the VALUE of the pair. All entries with unrecognized NAME values will be ignored. The db_config array must be NULL terminated.

DB_CONFIG

The same information specified to the db_config argument to db_appinit may be specified using a configuration file. If a database home directory has been specified (either by the application specifying a non-NULL db_home argument to db_appinit, 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. All lines with unrecognized NAME values will be ignored.

The following NAME VALUE pairs in the db_config argument and the DB_CONFIG file are currently supported by Berkeley DB.

DB_DATA_DIR

The path of a directory to be used as the location of the access method data files, e.g., paths specified to the db_open function will be relative to this path.

The DB_DATA_DIR paths are additive, and specifying more than one will result in each specified directory being searched for database data files. If multiple paths are specified, created data files will always be created in the first directory specified.

DB_LOG_DIR

The path of a directory to be used as the location of logging files, e.g., files created by the Log Manager subsystem will be relative to this directory. If specified, this is the directory name that will be passed to log_open.

DB_TMP_DIR

The path of a directory to be used as the location of temporary files, e.g., files created to back in-memory access method databases will be created relative to this path. Note, these temporary files can potentially be quite large, depending on the size of the database.

If DB_TMP_DIR is not specified, the following environment variables are checked in order: TMPDIR, TEMP, TMP, TempFolder. If one of them is set, temporary files are created relative to the directory it specifies.

If DB_TMP_DIR is not specified and none of the above environment variables are set, the first possible one of the following directories is used: /var/tmp, /usr/tmp, /temp, /tmp, C:/temp and C:/tmp.

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_CONFIG

If a relevant configuration string (e.g., DB_DATA_DIR), is specified 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 begins with a leading slash, the file name is used without further modification by Berkeley DB.

The DB_CONFIG configuration file is intended to permit systems to customize file location for a database 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.

db_config

If a relevant configuration string (e.g., DB_DATA_DIR), is specified in the db_config argument and is not specified in the DB_CONFIG file, the VALUE from the NAME VALUE pair is prepended to the current file name. If the resulting file name begins with a leading slash, the file name is used without further modification by Berkeley DB.

The db_config argument is 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_HOME

If 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 begins with a leading slash, the file name is used without further modification by Berkeley DB.

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

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

db_home

If the application specified a non-NULL db_home argument to db_appinit (and the database home was not already specified using the DB_HOME environment variable) its value is prepended to the current file name. If the resulting file name begins with a leading slash, 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 files will be presumed to be 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 db_appinit, and then DB_DATA_DIR and DB_LOG_DIR are set to the relative path names of directories underneath the home directory using the db_config argument to db_appinit or the DB_CONFIG file.

Examples

db_appinit("/a/database", NULL, ...);

Create temporary backing files in /b/temporary, and all other files in /a/database:

char *config = {
    "DB_TMP_DIR /b/temporary",
    NULL
};
db_appinit("/a/database", config, ...);

Store data files in /a/database/datadir, log files in /a/database/logdir, and all other files in the directory /a/database:

char *config = {
    "DB_DATA_DIR datadir",
    "DB_LOG_DIR logdir",
    NULL
};
db_appinit("/a/database", config, ...);

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:

char *config = {
    "DB_DATA_DIR /b/data2",
    "DB_DATA_DIR data1",
    NULL
};
db_appinit("/a/database", config, ...);

See the file examples/ex_appinit.c in the Berkeley DB source distribution for an example of how an application might use db_appinit to configure its Berkeley DB environment.