- One of the most important tasks of the database environment is to - structure file naming within Berkeley DB. Cooperating applications (or - multiple invocations of the same application) must agree on the - location of the database environment, log files and other files used by - the Berkeley DB subsystems, and, of course, the database files. - Although it is possible to specify full pathnames to all Berkeley DB - methods, this is cumbersome and requires applications be recompiled - when database files are moved. -

Prev	Chapter 9. - The Berkeley DB Environment -	Chapter 9. The Berkeley DB Environment	Next

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

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

Specifying file naming to Berkeley DB

- The following list 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. -

+ The following list 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_ENV->open() is non-NULL, its value may be used as the - database home, and files named relative to its path. -

DB_HOME

db_homeDB_ENV->open()

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

+ If the DB_HOME environment variable is set + when DB_ENV->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. For example: -

+ The DB_HOME environment variable is + intended to permit users and system + administrators to override application and + installation defaults. For example: +

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. -

+ 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 four DB_ENV methods that affect file naming: -

+ There are four DB_ENV methods that affect + file naming: +

-
- The DB_ENV->add_data_dir() method specifies a - directory to search for database files. -
+
+ The DB_ENV->add_data_dir() method + specifies a directory to search for + database files. +
-
- The DB_ENV->set_lg_dir() method specifies a - directory in which to create logging files. -
+
+ The DB_ENV->set_lg_dir() method + specifies a directory in which to + create logging files. +
- The DB_ENV->set_tmp_dir() method specifies a - directory in which to create backing temporary - files. -
+ The DB_ENV->set_tmp_dir() method + specifies a directory in which to + create backing temporary files. +
- The DB_ENV->set_metadata_dir() method specifies the - directory in which to create persistent - metadata files used by the environment. -
+ The DB_ENV->set_metadata_dir() method + specifies the directory in which to + create persistent metadata files used + by the environment. +

- These methods are intended to permit applications to - customize a file locations for an environment. 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. -

+ These methods are intended to permit + applications to customize a file locations for + an environment. 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 - + DB_CONFIG +

- The same information specified to the DB_ENV methods may - also be specified using the - DB_CONFIG - configuration file. -

+ The same information specified to the DB_ENV + methods may also be specified using the DB_CONFIG + configuration file. +

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

absolute pathnames

- If the filename specified to a Berkeley DB function is - an absolute pathname, that - filename 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 (for example, - C:/tmp). -

+ If the filename specified to a Berkeley DB + function is an absolute + pathname, that filename 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 (for example, + C:/tmp). +

DB_ENV methods, DB_CONFIG

- If a relevant configuration string (for example, - set_data_dir), is specified either by calling a DB_ENV - method or as a line in the - DB_CONFIG configuration - file, the value is prepended to the filename. If the - resulting filename is an absolute pathname, the filename is - used without further modification by Berkeley - DB. -

+ If a relevant configuration string (for + example, add_data_dir), is specified either by + calling a DB_ENV method or as a line in the DB_CONFIG + configuration file, the value is prepended to the + filename. If the resulting filename is an absolute + pathname, the filename is used without further + modification by Berkeley DB. +

db_home

- If the application specified a non-NULL - db_home argument to - DB_ENV->open(), its value is prepended to the filename. If the - resulting filename is an absolute pathname, the filename is - used without further modification by Berkeley - DB. -

+ If the application specified a non-NULL + db_home + argument to DB_ENV->open(), its value is prepended to + the filename. If the resulting filename is an + absolute pathname, the filename 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 flags, its value is prepended to the - filename. If the resulting filename is an absolute - pathname, the filename is used without further modification - by Berkeley DB. -

default

db_homeDB_USE_ENVIRONDB_USE_ENVIRON_ROOT - Finally, all filenames are interpreted relative to the - current working directory of the process. -

- The common model for a Berkeley DB environment is one in which only - the DB_HOME environment variable, or the - db_home argument is specified. In - this case, all data filenames 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 - in which a database home is specified, using either the DB_HOME - environment variable or the - db_home argument to DB_ENV->open(); and - then the data directory and logging directory are set to the - relative pathnames of directories underneath the environment - home. -

Examples

- Store all files in the directory /a/database: -

+ Store all files in the directory + /a/database: +

dbenv->open(dbenv, "/a/database", flags, mode);

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

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

dbenv->set_tmp_dir(dbenv, "/b/temporary");
 dbenv->open(dbenv, "/a/database", flags, mode);

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

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

dbenv->set_lg_dir(dbenv, "logdir");
-dbenv->set_data_dir(dbenv, "datadir");
+dbenv->add_data_dir(dbenv, "datadir");
 dbenv->open(dbenv, "/a/database", flags, mode);

- 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 data file directory specified: -

dbenv->set_data_dir(dbenv, "/b/data2");
-dbenv->set_data_dir(dbenv, "data1");
+         
+            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
+            data file directory specified: 
+        
+        dbenv->add_data_dir(dbenv, "/b/data2");
+dbenv->add_data_dir(dbenv, "data1");
 dbenv->open(dbenv, "/a/database", flags, mode);

Specifying file naming to Berkeley DB

Specifying file naming to Berkeley DB

Filename resolution in Berkeley DB

Filename resolution in Berkeley DB

Examples

Examples