Library Version 11.2.5.3

Library Version 12.1.6.1

- + - +

Opening multiple databases in a single file			Opening multiple databases in a + single file
Prev	Chapter 3. - Access Method Operations -	Chapter 3. Access Method Operations	Next

@@ -34,7 +33,8 @@

Opening multiple databases in a single file

Opening multiple databases in a + single file

@@ -42,103 +42,137 @@

- Configuring databases sharing a file + Configuring databases sharing a file
- Caching databases sharing a file + Caching databases sharing a file
- Locking in databases based on sharing a file + Locking in databases based on sharing a file

Applications may create multiple databases within a single physical -file. This is useful when the databases are both numerous and -reasonably small, in order to avoid creating a large number of -underlying files, or when it is desirable to include secondary index -databases in the same file as the primary index database. Putting -multiple databases in a single physical file is an administrative -convenience and unlikely to affect database performance.

To open or create a file that will include more than a single database, -specify a database name when calling the DB->open() method.

Physical files do not need to be comprised of a single type of database, -and databases in a file may be of any mixture of types, except for Queue and Heap -databases. Queue and Heap databases must be created one per file and cannot -share a file with any other database type. There is no limit on the -number of databases that may be created in a single file other than the -standard Berkeley DB file size and disk space limitations.

It is an error to attempt to open a second database in a file that was -not initially created using a database name, that is, the file must -initially be specified as capable of containing multiple databases for a -second database to be created in it.

It is not an error to open a file that contains multiple databases -without specifying a database name, however the database type should be -specified as DB_UNKNOWN and the database must be opened read-only. The -handle that is returned from such a call is a handle on a database whose -key values are the names of the databases stored in the database file -and whose data values are opaque objects. No keys or data values may be -modified or stored using this database handle.

+ Applications may create multiple databases within a single + physical file. This is useful when the databases are both + numerous and reasonably small, in order to avoid creating a + large number of underlying files, or when it is desirable to + include secondary index databases in the same file as the + primary index database. Putting multiple databases in a single + physical file is an administrative convenience and unlikely to + affect database performance. +

+ To open or create a file that will include more than a + single database, specify a database name when calling the + DB->open() method. +

+ Physical files do not need to be comprised of a single type + of database, and databases in a file may be of any mixture of + types, except for Queue and Heap databases. Queue and Heap + databases must be created one per file and cannot share a file + with any other database type. There is no limit on the number + of databases that may be created in a single file other than + the standard Berkeley DB file size and disk space + limitations. +

+ It is an error to attempt to open a second database in a + file that was not initially created using a database name, + that is, the file must initially be specified as capable of + containing multiple databases for a second database to be + created in it. +

+ It is not an error to open a file that contains multiple + databases without specifying a database name, however the + database type should be specified as DB_UNKNOWN and the + database must be opened read-only. The handle that is returned + from such a call is a handle on a database whose key values + are the names of the databases stored in the database file and + whose data values are opaque objects. No keys or data values + may be modified or stored using this database handle. +

Configuring databases sharing a file

There are four pieces of configuration information which must be -specified consistently for all databases in a file, rather than -differing on a per-database basis. They are: byte order, checksum and -encryption behavior, and page size. When creating additional databases -in a file, any of these configuration values specified must be -consistent with the existing databases in the file or an error will be -returned.

+ There are four pieces of configuration information which + must be specified consistently for all databases in a + file, rather than differing on a per-database basis. They + are: byte order, checksum and encryption behavior, and + page size. When creating additional databases in a file, + any of these configuration values specified must be + consistent with the existing databases in the file or an + error will be returned. +

Caching databases sharing a file

When storing multiple databases in a single physical file rather than -in separate files, if any of the databases in a file is opened for -update, all of the databases in the file must share a memory pool. In -other words, they must be opened in the same database environment. This -is so per-physical-file information common between the two databases is -updated correctly.

+ When storing multiple databases in a single physical + file rather than in separate files, if any of the + databases in a file is opened for update, all of the + databases in the file must share a memory pool. In other + words, they must be opened in the same database + environment. This is so per-physical-file information + common between the two databases is updated + correctly. +

Locking in databases based on sharing a file

If databases are in separate files (and access to each separate database -is single-threaded), there is no reason to perform any locking of any -kind, and the two databases may be read and written simultaneously. -Further, there would be no requirement to create a shared database -environment in which to open those two databases.

However, since multiple databases in a file exist in a single physical -file, opening two databases in the same file simultaneously requires -locking be enabled, unless all of the databases are read-only. As the -locks for the two databases can only conflict during page allocation, -this additional locking is unlikely to affect performance. The -exception is when Berkeley DB Concurrent Data Store is configured; a single lock is used for all -databases in the file when Berkeley DB Concurrent Data Store is configured, and a write to one -database will block all accesses to all databases.

In summary, programmers writing applications that open multiple -databases in a single file will almost certainly need to create a shared -database environment in the application as well. For more information -on database environments, see Database environment introduction

+ If databases are in separate files (and access to each + separate database is single-threaded), there is no reason + to perform any locking of any kind, and the two databases + may be read and written simultaneously. Further, there + would be no requirement to create a shared database + environment in which to open those two databases. +

+ However, since multiple databases in a file exist in a + single physical file, opening two databases in the same + file simultaneously requires locking be enabled, unless + all of the databases are read-only. As the locks for the + two databases can only conflict during page allocation, + this additional locking is unlikely to affect performance. + The exception is when Berkeley DB Concurrent Data Store is + configured; a single lock is used for all databases in the + file when Berkeley DB Concurrent Data Store is configured, + and a write to one database will block all accesses to all + databases. +

+ In summary, programmers writing applications that open + multiple databases in a single file will almost certainly + need to create a shared database environment in the + application as well. For more information on database + environments, see Database environment introduction +