1<?xml version="1.0" encoding="UTF-8" standalone="no"?> 2<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"> 3<html xmlns="http://www.w3.org/1999/xhtml"> 4 <head> 5 <meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /> 6 <title>Opening multiple databases in a single file</title> 7 <link rel="stylesheet" href="gettingStarted.css" type="text/css" /> 8 <meta name="generator" content="DocBook XSL Stylesheets V1.73.2" /> 9 <link rel="start" href="index.html" title="Berkeley DB Programmer's Reference Guide" /> 10 <link rel="up" href="am.html" title="Chapter��3.�� Access Method Operations" /> 11 <link rel="prev" href="am.html" title="Chapter��3.�� Access Method Operations" /> 12 <link rel="next" href="am_partition.html" title="Partitioning databases" /> 13 </head> 14 <body> 15 <div class="navheader"> 16 <table width="100%" summary="Navigation header"> 17 <tr> 18 <th colspan="3" align="center">Opening multiple databases in a single file</th> 19 </tr> 20 <tr> 21 <td width="20%" align="left"><a accesskey="p" href="am.html">Prev</a>��</td> 22 <th width="60%" align="center">Chapter��3.�� 23 Access Method Operations 24 </th> 25 <td width="20%" align="right">��<a accesskey="n" href="am_partition.html">Next</a></td> 26 </tr> 27 </table> 28 <hr /> 29 </div> 30 <div class="sect1" lang="en" xml:lang="en"> 31 <div class="titlepage"> 32 <div> 33 <div> 34 <h2 class="title" style="clear: both"><a id="am_opensub"></a>Opening multiple databases in a single file</h2> 35 </div> 36 </div> 37 </div> 38 <div class="toc"> 39 <dl> 40 <dt> 41 <span class="sect2"> 42 <a href="am_opensub.html#id1591610">Configuring databases sharing a file</a> 43 </span> 44 </dt> 45 <dt> 46 <span class="sect2"> 47 <a href="am_opensub.html#id1592728">Caching databases sharing a file</a> 48 </span> 49 </dt> 50 <dt> 51 <span class="sect2"> 52 <a href="am_opensub.html#id1592798">Locking in databases based on sharing a file</a> 53 </span> 54 </dt> 55 </dl> 56 </div> 57 <p>Applications may create multiple databases within a single physical 58file. This is useful when the databases are both numerous and 59reasonably small, in order to avoid creating a large number of 60underlying files, or when it is desirable to include secondary index 61databases in the same file as the primary index database. Putting 62multiple databases in a single physical file is an administrative 63convenience and unlikely to affect database performance.</p> 64 <p>To open or create a file that will include more than a single database, 65specify a database name when calling the <a href="../api_reference/C/dbopen.html" class="olink">DB->open()</a> method.</p> 66 <p>Physical files do not need to be comprised of a single type of database, 67and databases in a file may be of any mixture of types, except for Queue 68databases. Queue databases must be created one per file and cannot 69share a file with any other database type. There is no limit on the 70number of databases that may be created in a single file other than the 71standard Berkeley DB file size and disk space limitations.</p> 72 <p>It is an error to attempt to open a second database in a file that was 73not initially created using a database name, that is, the file must 74initially be specified as capable of containing multiple databases for a 75second database to be created in it.</p> 76 <p>It is not an error to open a file that contains multiple databases 77without specifying a database name, however the database type should be 78specified as DB_UNKNOWN and the database must be opened read-only. The 79handle that is returned from such a call is a handle on a database whose 80key values are the names of the databases stored in the database file 81and whose data values are opaque objects. No keys or data values may be 82modified or stored using this database handle.</p> 83 <div class="sect2" lang="en" xml:lang="en"> 84 <div class="titlepage"> 85 <div> 86 <div> 87 <h3 class="title"><a id="id1591610"></a>Configuring databases sharing a file</h3> 88 </div> 89 </div> 90 </div> 91 <p>There are four pieces of configuration information which must be 92specified consistently for all databases in a file, rather than 93differing on a per-database basis. They are: byte order, checksum and 94encryption behavior, and page size. When creating additional databases 95in a file, any of these configuration values specified must be 96consistent with the existing databases in the file or an error will be 97returned.</p> 98 </div> 99 <div class="sect2" lang="en" xml:lang="en"> 100 <div class="titlepage"> 101 <div> 102 <div> 103 <h3 class="title"><a id="id1592728"></a>Caching databases sharing a file</h3> 104 </div> 105 </div> 106 </div> 107 <p>When storing multiple databases in a single physical file rather than 108in separate files, if any of the databases in a file is opened for 109update, all of the databases in the file must share a memory pool. In 110other words, they must be opened in the same database environment. This 111is so per-physical-file information common between the two databases is 112updated correctly.</p> 113 </div> 114 <div class="sect2" lang="en" xml:lang="en"> 115 <div class="titlepage"> 116 <div> 117 <div> 118 <h3 class="title"><a id="id1592798"></a>Locking in databases based on sharing a file</h3> 119 </div> 120 </div> 121 </div> 122 <p>If databases are in separate files (and access to each separate database 123is single-threaded), there is no reason to perform any locking of any 124kind, and the two databases may be read and written simultaneously. 125Further, there would be no requirement to create a shared database 126environment in which to open those two databases.</p> 127 <p>However, since multiple databases in a file exist in a single physical 128file, opening two databases in the same file simultaneously requires 129locking be enabled, unless all of the databases are read-only. As the 130locks for the two databases can only conflict during page allocation, 131this additional locking is unlikely to affect performance. The 132exception is when Berkeley DB Concurrent Data Store is configured; a single lock is used for all 133databases in the file when Berkeley DB Concurrent Data Store is configured, and a write to one 134database will block all accesses to all databases.</p> 135 <p>In summary, programmers writing applications that open multiple 136databases in a single file will almost certainly need to create a shared 137database environment in the application as well. For more information 138on database environments, see <a class="xref" href="env.html#env_intro" title="Database environment introduction">Database environment introduction</a></p> 139 </div> 140 </div> 141 <div class="navfooter"> 142 <hr /> 143 <table width="100%" summary="Navigation footer"> 144 <tr> 145 <td width="40%" align="left"><a accesskey="p" href="am.html">Prev</a>��</td> 146 <td width="20%" align="center"> 147 <a accesskey="u" href="am.html">Up</a> 148 </td> 149 <td width="40%" align="right">��<a accesskey="n" href="am_partition.html">Next</a></td> 150 </tr> 151 <tr> 152 <td width="40%" align="left" valign="top">Chapter��3.�� 153 Access Method Operations 154 ��</td> 155 <td width="20%" align="center"> 156 <a accesskey="h" href="index.html">Home</a> 157 </td> 158 <td width="40%" align="right" valign="top">��Partitioning databases</td> 159 </tr> 160 </table> 161 </div> 162 </body> 163</html> 164