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
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().

Database Operations Description
db_create() Create a database handle
DB->associate() Associate a secondary index
DB->associate_foreign() Associate a foreign index
DB->close() Close a database
DB->compact() Compact a database
DB->cursor() Create a cursor
DB->del() Delete items from a database
DB->err() Error message
DB->existis() Return if an item appears in a database
DB->fd() Return a file descriptor from a database
DB->get() Get items from a database
DB->get_byteswapped() Return if the underlying database is in host order
DB->get_type() Return the database type
DB->join() Perform a database join on cursors
DB->key_range() Return estimate of key location
DB->open() Open a database
DB->put() Store items into a database
DB->remove() Remove a database
DB->rename() Rename a database
DB->set_priority() Set cache page priority
DB->stat() Database statistics
DB->sync() Flush a database to stable storage
DB->truncate() Empty a database
DB->upgrade() Upgrade a database
DB->verify() Verify/salvage a database
Database Configuration  
DB->set_alloc() Set local space allocation functions
DB->set_cachesize() Set the database cache size
DB->set_dup_compare() Set a duplicate comparison function
DB->set_encrypt() Set the database cryptographic key
DB->set_errcall() Set error and informational message callback
DB->set_errfile() Set error and informational message FILE
DB->set_errpfx() Set error message prefix
DB->set_feedback() Set feedback callback
DB->set_flags() General database configuration
DB->set_lorder() Set the database byte order
DB->set_pagesize() Set the underlying database page size
Btree/Recno Configuration  
DB->set_append_recno() Set record append callback
DB->set_bt_compare() Set a Btree comparison function
DB->set_bt_minkey() Set the minimum number of keys per Btree page
DB->set_bt_prefix() Set a Btree prefix comparison function
DB->set_re_delim() Set the variable-length record delimiter
DB->set_re_len() Set the fixed-length record length
DB->set_re_pad() Set the fixed-length record pad byte
DB->set_re_source() Set the backing Recno text file
Hash Configuration  
DB->set_h_compare() Set a Hash comparison function
DB->set_h_ffactor() Set the Hash table density
DB->set_h_hash() Set a hashing function
DB->set_h_nelem() Set the Hash table size
Queue Configuration  
DB->set_q_extentsize() Set Queue database extent size

Database open

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

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

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

Create the underlying database and any necessary physical files.
Do not map this database into process memory.
Treat the data base as read-only.
The returned handle is free-threaded, that is, it can be used simultaneously by multiple threads within the process.
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.
Upgrade the database format as necessary.