1<!--$Id: opensub.so,v 10.20 2007/05/17 18:31:55 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: Opening multiple databases in a single file</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<table width="100%"><tr valign=top> 12<td><b><dl><dt>Berkeley DB Reference Guide:<dd>Access Methods</dl></b></td> 13<td align=right><a href="/am/open.html"><img src="/images/prev.gif" alt="Prev"></a><a href="/toc.html"><img src="/images/ref.gif" alt="Ref"></a><a href="/am/get.html"><img src="/images/next.gif" alt="Next"></a> 14</td></tr></table> 15<p align=center><b>Opening multiple databases in a single file</b></p> 16<p>Applications may create multiple databases within a single physical 17file. This is useful when the databases are both numerous and 18reasonably small, in order to avoid creating a large number of 19underlying files, or when it is desirable to include secondary index 20databases in the same file as the primary index database. Putting 21multiple databases in a single physical file is an administrative 22convenience and unlikely to affect database performance.</p> 23<p>To open or create a file that will include more than a single database, 24specify a database name when calling the <a href="/api_c/db_open.html">DB->open</a> method.</p> 25<p>Physical files do not need to be comprised of a single type of database, 26and databases in a file may be of any mixture of types, except for Queue 27databases. Queue databases must be created one per file and cannot 28share a file with any other database type. There is no limit on the 29number of databases that may be created in a single file other than the 30standard Berkeley DB file size and disk space limitations.</p> 31<p>It is an error to attempt to open a second database in a file that was 32not initially created using a database name, that is, the file must 33initially be specified as capable of containing multiple databases for a 34second database to be created in it.</p> 35<p>It is not an error to open a file that contains multiple databases 36without specifying a database name, however the database type should be 37specified as DB_UNKNOWN and the database must be opened read-only. The 38handle that is returned from such a call is a handle on a database whose 39key values are the names of the databases stored in the database file 40and whose data values are opaque objects. No keys or data values may be 41modified or stored using this database handle.</p> 42<b>Configuring databases sharing a file</b> 43<p>There are four pieces of configuration information which must be 44specified consistently for all databases in a file, rather than 45differing on a per-database basis. They are: byte order, checksum and 46encryption behavior, and page size. When creating additional databases 47in a file, any of these configuration values specified must be 48consistent with the existing databases in the file or an error will be 49returned.</p> 50<b>Caching databases sharing a file</b> 51<p>When storing multiple databases in a single physical file rather than 52in separate files, if any of the databases in a file is opened for 53update, all of the databases in the file must share a memory pool. In 54other words, they must be opened in the same database environment. This 55is so per-physical-file information common between the two databases is 56updated correctly.</p> 57<b>Locking in databases based on sharing a file</b> 58<p>If databases are in separate files (and access to each separate database 59is single-threaded), there is no reason to perform any locking of any 60kind, and the two databases may be read and written simultaneously. 61Further, there would be no requirement to create a shared database 62environment in which to open those two databases.</p> 63<p>However, since multiple databases in a file exist in a single physical 64file, opening two databases in the same file simultaneously requires 65locking be enabled, unless all of the databases are read-only. As the 66locks for the two databases can only conflict during page allocation, 67this additional locking is unlikely to affect performance. The 68exception is when Berkeley DB Concurrent Data Store is configured; a single lock is used for all 69databases in the file when Berkeley DB Concurrent Data Store is configured, and a write to one 70database will block all accesses to all databases.</p> 71<p>In summary, programmers writing applications that open multiple 72databases in a single file will almost certainly need to create a shared 73database environment in the application as well. For more information 74on database environments, see <a href="/ref/env/intro.html">Database 75environment introduction.</a></p> 76<table width="100%"><tr><td><br></td><td align=right><a href="/am/open.html"><img src="/images/prev.gif" alt="Prev"></a><a href="/toc.html"><img src="/images/ref.gif" alt="Ref"></a><a href="/am/get.html"><img src="/images/next.gif" alt="Next"></a> 77</td></tr></table> 78<p><font size=1>Copyright (c) 1996,2008 Oracle. All rights reserved.</font> 79</body> 80</html> 81