Chapter 3.  Access Method Operations

Table of Contents

Database open
Opening multiple databases in a single file
Configuring databases sharing a file
Caching databases sharing a file
Locking in databases based on sharing a file
Partitioning databases
Specifying partition keys
Partitioning callback
Placing partition files
Retrieving records
Storing records
Deleting records
Database statistics
Database truncation
Database upgrade
Database verification and salvage
Flushing the database cache
Database close
Secondary indexes
Error Handling With Secondary Indexes
Foreign key indexes
Cursor operations
Retrieving records with a cursor
Storing records with a cursor
Deleting records with a cursor
Duplicating a cursor
Equality Join
Data item count
Cursor close

Once a database handle has been created using db_create(), there are several standard access method operations. Each of these operations is performed using a method referred to by the returned handle. Generally, the database will be opened using DB->open(). If the database is from an old release of Berkeley DB, it may need to be upgraded to the current release before it is opened using DB->upgrade().

Once a database has been opened, records may be retrieved (DB->get()), stored (DB->put()), and deleted (DB->del()).

Additional operations supported by the database handle include statistics (DB->stat()), truncation (DB->truncate()), version upgrade (DB->upgrade()), verification and salvage (DB->verify()), flushing to a backing file (DB->sync()), and association of secondary indices (DB->associate()). Database handles are eventually closed using DB->close().

For more information on the access method operations supported by the database handle, see the Database and Related Methods section in the Berkeley DB C API Reference Guide.

Database open

The DB->open() method opens a database, and takes five arguments:

file
The name of the file to be opened.
database
An optional database name.
type
The type of database to open. This value will be one of the five access methods Berkeley DB supports: DB_BTREE, DB_HASH, DB_HEAP, DB_QUEUE or DB_RECNO, or the special value DB_UNKNOWN, which allows you to open an existing file without knowing its type.
mode
The permissions to give to any created file.

There are a few flags that you can set to customize open:

DB_CREATE
Create the underlying database and any necessary physical files.
DB_NOMMAP
Do not map this database into process memory.
DB_RDONLY
Treat the data base as read-only.
DB_THREAD
The returned handle is free-threaded, that is, it can be used simultaneously by multiple threads within the process.
DB_TRUNCATE
Physically truncate the underlying database file, discarding all databases it contained. Underlying filesystem primitives are used to implement this flag. For this reason it is only applicable to the physical file and cannot be used to discard individual databases from within physical files.
DB_UPGRADE
Upgrade the database format as necessary.