Berkeley DB Reference Guide: Simple Tutorial ee,hash,hashing,transaction,transactions,locking,logging,access method,access me thods,java,C,C++">

Berkeley DB Reference Guide: Simple Tutorial

Adding elements to a database

The simplest way to add elements to a database is the DB->put interface. This interface is accessed through a function pointer that is an element of the database handle returned by db_open. (All Berkeley DB handles contain function pointers you must use to operate on the objects to which the handles refer.)

The DB->put interface takes five arguments:

db: The database handle returned by db_open.
txnid: A transaction ID. In our simple case, we aren't expecting to recover the database after application or system crash, so we aren't using transactions, and will leave this argument unspecified.
key: The key item for the key/data pair that we want to add to the database.
data: The data item for the key/data pair that we want to add to the database.
flags: Optional flags modifying the underlying behavior of the DB->put interface.

Here's what the code to call DB->put looks like:

#include <sys/types.h>
#include <stdio.h>
#include <db.h>

#define	DATABASE	"access.db"

int
main()
{
	extern int errno;
	DB *dbp;
	DBT key, data;

	if ((errno = db_open(DATABASE,
	    DB_BTREE, DB_CREATE, 0664, NULL, NULL, &dbp)) != 0) {
		fprintf(stderr, "db: %s: %s\n", DATABASE, strerror(errno));
		exit (1);
	}

	memset(&key, 0, sizeof(key));
	memset(&data, 0, sizeof(data));
	key.data = "fruit";
	key.size = sizeof("fruit");
	data.data = "apple";
	data.size = sizeof("apple");

	switch (errno = dbp->put(dbp, NULL, &key, &data, 0)) {
	case 0:
		printf("db: %s: key stored.\n", (char *)key.data);
		break;
	default:
		fprintf(stderr, "db: put: %s\n", strerror(errno));
		exit (1);
	}

The first thing to notice about this new code is that we're clearing the structures that we're about to pass as arguments to Berkeley DB functions. This is very important, and being careful to do so will result in fewer subtle errors in your programs. All structures specified to Berkeley DB interfaces should be cleared before use, without exception. The reason that this is necessary is that future versions of Berkeley DB may add additional fields to the structures. If applications are careful to clear the structures before use, it will be possible for Berkeley DB to change those structures without requiring that the applications be rewritten to be aware of the changes.

Notice also that we're storing the trailing nul byte found in the C strings "fruit" and "apple" in both the key and data items, that is, the trailing nul byte is part of the stored key, and therefore has to be specified in order to access the data item. There is no requirement to store the trailing nul byte, it simply makes it easier for us to display strings that we've stored using programming languages that use nul bytes to terminate strings.

In many databases, it is important not to overwrite already existing data. For example, we might not want to store the key/data pair fruit/apple if it already existed, e.g., if someone had previously stored the key/data pair fruit/cherry into the database.

This is easily accomplished using the following code:

#include <sys/types.h>
#include <stdio.h>
#include <db.h>

#define	DATABASE	"access.db"

int
main()
{
	extern int errno;
	DB *dbp;
	DBT key, data;

	if ((errno = db_open(DATABASE,
	    DB_BTREE, DB_CREATE, 0664, NULL, NULL, &dbp)) != 0) {
		fprintf(stderr, "db: %s: %s\n", DATABASE, strerror(errno));
		exit (1);
	}


	memset(&key, 0, sizeof(key));
	memset(&data, 0, sizeof(data));
	key.data = "fruit";
	key.size = sizeof("fruit");
	data.data = "apple";
	data.size = sizeof("apple");

	switch (errno = dbp->put(dbp, NULL, &key, &data, DB_NOOVERWRITE)) {
	case 0:
		printf("db: %s: key stored.\n", (char *)key.data);
		break;
	case DB_KEYEXIST:
		printf("%s: key already exists\n", (char *)key.data);
		break;
	default:
		fprintf(stderr, "db: put: %s\n", strerror(errno));
		exit (1);
	}

To accomplish this task, we've specified a flag to the DB->put call: DB_NOOVERWRITE, which causes the underlying database functions to not overwrite any previously existing key/data pair. (Note that the value of the previously existing data doesn't matter for this case. The only issue is if a key/data pair already exists where the key matches the key that we are trying to store.)

Specifying DB_NOOVERWRITE opens the possibility of a new error return, DB_KEYEXIST, which means we were unable to add the key/data pair to the database because the key already existed in the database.