1<!--$Id: create.so,v 10.30 2005/09/23 16:22:42 bostic Exp $--> 2<!--Copyright (c) 1997,2008 Oracle. All rights reserved.--> 3<!--See the file LICENSE for redistribution information.--> 4<html> 5<head> 6<title>Berkeley DB Reference Guide: Creating a database environment</title> 7<meta name="description" content="Berkeley DB: An embedded database programmatic toolkit."> 8<meta name="keywords" content="embedded,database,programmatic,toolkit,btree,hash,hashing,transaction,transactions,locking,logging,access method,access methods,Java,C,C++"> 9</head> 10<body bgcolor=white> 11<a name="2"><!--meow--></a> 12<table width="100%"><tr valign=top> 13<td><b><dl><dt>Berkeley DB Reference Guide:<dd>Environment</dl></b></td> 14<td align=right><a href="/env/intro.html"><img src="/images/prev.gif" alt="Prev"></a><a href="/toc.html"><img src="/images/ref.gif" alt="Ref"></a><a href="/env/open.html"><img src="/images/next.gif" alt="Next"></a> 15</td></tr></table> 16<p align=center><b>Creating a database environment</b></p> 17<p>The Berkeley DB environment is created and described by the <a href="/api_c/env_class.html">db_env_create</a> 18and <a href="/api_c/env_open.html">DB_ENV->open</a> interfaces. In situations where customization is 19desired, such as storing log files on a separate disk drive or selection 20of a particular cache size, applications must describe the customization 21by either creating an environment configuration file in the environment 22home directory or by arguments passed to other <a href="/api_c/env_class.html">DB_ENV</a> handle methods.</p> 23<p>Once an environment has been created, database files specified using 24relative pathnames will be named relative to the home directory. Using 25pathnames relative to the home directory allows the entire environment 26to be easily moved, simplifying restoration and recovery of a database 27in a different directory or on a different system.</p> 28<p>Applications first obtain an environment handle using the 29<a href="/api_c/env_class.html">db_env_create</a> method, then call the <a href="/api_c/env_open.html">DB_ENV->open</a> method which creates 30or joins the database environment. There are a number of options you 31can set to customize <a href="/api_c/env_open.html">DB_ENV->open</a> for your environment. These 32options fall into four broad categories:</p> 33<br> 34<b>Subsystem Initialization:</b><ul compact><li>These flags indicate which Berkeley DB subsystems will be initialized for the 35environment, and what operations will happen automatically when 36databases are accessed within the environment. The flags include 37<a href="/api_c/env_open.html#DB_INIT_CDB">DB_INIT_CDB</a>, <a href="/api_c/env_open.html#DB_INIT_LOCK">DB_INIT_LOCK</a>, <a href="/api_c/env_open.html#DB_INIT_LOG">DB_INIT_LOG</a>, 38<a href="/api_c/env_open.html#DB_INIT_MPOOL">DB_INIT_MPOOL</a>, and <a href="/api_c/env_open.html#DB_INIT_TXN">DB_INIT_TXN</a>. The <a href="/api_c/env_open.html#DB_INIT_CDB">DB_INIT_CDB</a> 39flag does initialization for Berkeley DB Concurrent Data Store applications. (See 40<a href="/ref/cam/intro.html">Building Berkeley DB Concurrent Data Store applications</a> for more 41information.) The rest of the flags initialize a single subsystem; that 42is, when <a href="/api_c/env_open.html#DB_INIT_LOCK">DB_INIT_LOCK</a> is specified, applications reading and 43writing databases opened in this environment will be using locking to 44ensure that they do not overwrite each other's changes.</ul> 45<b>Recovery options:</b><ul compact><li>These flags, which include <a href="/api_c/env_open.html#DB_RECOVER">DB_RECOVER</a> and 46<a href="/api_c/env_open.html#DB_RECOVER_FATAL">DB_RECOVER_FATAL</a>, indicate what recovery is to be performed on 47the environment before it is opened for normal use.</ul> 48<b>Naming options:</b><ul compact><li>These flags, which include <a href="/api_c/env_open.html#DB_USE_ENVIRON">DB_USE_ENVIRON</a> and 49<a href="/api_c/env_open.html#DB_USE_ENVIRON_ROOT">DB_USE_ENVIRON_ROOT</a>, modify how file naming happens in the 50environment.</ul> 51<b>Miscellaneous:</b><ul compact><li>Finally, there are a number of miscellaneous flags, for example, 52<a href="/api_c/env_open.html#DB_CREATE">DB_CREATE</a> which causes underlying files to be created as 53necessary. See the <a href="/api_c/env_open.html">DB_ENV->open</a> manual pages for further 54information.</ul> 55<br> 56<p>Most applications either specify only the <a href="/api_c/env_open.html#DB_INIT_MPOOL">DB_INIT_MPOOL</a> flag or 57they specify all four subsystem initialization flags 58(<a href="/api_c/env_open.html#DB_INIT_MPOOL">DB_INIT_MPOOL</a>, <a href="/api_c/env_open.html#DB_INIT_LOCK">DB_INIT_LOCK</a>, <a href="/api_c/env_open.html#DB_INIT_LOG">DB_INIT_LOG</a>, and 59<a href="/api_c/env_open.html#DB_INIT_TXN">DB_INIT_TXN</a>). The former configuration is for applications that 60simply want to use the basic Access Method interfaces with a shared 61underlying buffer pool, but don't care about recoverability after 62application or system failure. The latter is for applications that need 63recoverability. There are situations in which other combinations of 64the initialization flags make sense, but they are rare.</p> 65<p>The <a href="/api_c/env_open.html#DB_RECOVER">DB_RECOVER</a> flag is specified by applications that want to 66perform any necessary database recovery when they start running. That 67is, if there was a system or application failure the last time they ran, 68they want the databases to be made consistent before they start running 69again. It is not an error to specify this flag when no recovery needs 70to be done.</p> 71<p>The <a href="/api_c/env_open.html#DB_RECOVER_FATAL">DB_RECOVER_FATAL</a> flag is more special-purpose. It performs 72catastrophic database recovery, and normally requires that some initial 73arrangements be made; that is, archived log files be brought back into 74the filesystem. Applications should not normally specify this flag. 75Instead, under these rare conditions, the <a href="/utility/db_recover.html">db_recover</a> utility 76should be used.</p> 77<p>The following is a simple example of a function that opens a database 78environment for a transactional program.</p> 79<blockquote><pre>DB_ENV * 80db_setup(home, data_dir, errfp, progname) 81 char *home, *data_dir, *progname; 82 FILE *errfp; 83{ 84 DB_ENV *dbenv; 85 int ret; 86<p> 87 /* 88 * Create an environment and initialize it for additional error 89 * reporting. 90 */ 91 if ((ret = db_env_create(&dbenv, 0)) != 0) { 92 fprintf(errfp, "%s: %s\n", progname, db_strerror(ret)); 93 return (NULL); 94 } 95 dbenv->set_errfile(dbenv, errfp); 96 dbenv->set_errpfx(dbenv, progname); 97<p> 98 /* 99 * Specify the shared memory buffer pool cachesize: 5MB. 100 * Databases are in a subdirectory of the environment home. 101 */ 102 if ((ret = dbenv->set_cachesize(dbenv, 0, 5 * 1024 * 1024, 0)) != 0) { 103 dbenv->err(dbenv, ret, "set_cachesize"); 104 goto err; 105 } 106 if ((ret = dbenv->set_data_dir(dbenv, data_dir)) != 0) { 107 dbenv->err(dbenv, ret, "set_data_dir: %s", data_dir); 108 goto err; 109 } 110<p> 111 /* Open the environment with full transactional support. */ 112 if ((ret = dbenv->open(dbenv, home, DB_CREATE | 113 DB_INIT_LOG | DB_INIT_LOCK | DB_INIT_MPOOL | DB_INIT_TXN, 0)) != 0) { 114 dbenv->err(dbenv, ret, "environment open: %s", home); 115 goto err; 116 } 117<p> 118 return (dbenv); 119<p> 120err: (void)dbenv->close(dbenv, 0); 121 return (NULL); 122}</pre></blockquote> 123<table width="100%"><tr><td><br></td><td align=right><a href="/env/intro.html"><img src="/images/prev.gif" alt="Prev"></a><a href="/toc.html"><img src="/images/ref.gif" alt="Ref"></a><a href="/env/open.html"><img src="/images/next.gif" alt="Next"></a> 124</td></tr></table> 125<p><font size=1>Copyright (c) 1996,2008 Oracle. All rights reserved.</font> 126</body> 127</html> 128
