Berkeley DB Reference Guide: Access Methods

Opening multiple databases in a single 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. Multiple databases are an administrative convenience and using them is unlikely to effect 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 databases. Queue 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.

Storing multiple databases in a single file is identical to storing each database in a separate file with the exception of some configuration information and the likely need for locking and a shared underlying memory pool.

There are four types 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.

An additional difference is how locking and the underlying memory pool services must to be configured. As an example, consider two databases instantiated in two different physical files. If 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 the databases.

Because multiple databases in a file exist in a single physical file, opening two databases in the same file requires locking be enabled (unless access to the databases is known to be single-threaded, that is, only one of the databases is ever read or written at a time). As the locks for the two databases can only conflict during page allocation, this additional locking is unlikely to effect performance.

Also, because multiple databases in a file exist in a single physical file, opening two databases in the same file requires the databases share an underlying memory pool so that per-physical-file information common between the two databases is updated correctly.

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.

Copyright (c) 1996-2003 Sleepycat Software, Inc. - All rights reserved.