Berkeley DB Reference Guide: Simple Tutorial

Opening a database

Opening a database is done using the Berkeley DB db_open interface.

The db_open interface takes seven arguments:

file

The name of the database file to be opened.

type

The type of database to open. This value will be one of the three access methods Berkeley DB supports: DB_BTREE, DB_HASH, or DB_RECNO, or the special value DB_UNKNOWN, which allows you to open an existing file without knowing its type.

flags

Various flags that modify the behavior of db_open. In our simple case, we care only about one of these flags: DB_CREATE. This flag behaves similarly to the POSIX 1003.1 flag to the open system call, causing Berkeley DB to create the underlying database if it does not yet exist.

mode

The file mode of any underlying files that db_open will create. The mode behaves similarly to the POSIX 1003.1 mode argument to the open system call, and specifies an octal value for read, write and execute permission. Obviously, all we care about is reading and writing!

dbenv

Additional arguments describing the database environment in which the database will be opened. This argument isn't applicable now, and so we will leave it unspecified.

dbinfo

Additional information describing the database file to be opened. This argument is used to specify things like the underlying page size or a comparison function for B+tree databases. We don't need to specify any of these things for our simple example, and so we will leave it unspecified.

dbpp

A location in which to store the database handle that db_open will return on success.

Here's what the code to call db_open looks like:

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

#define	DATABASE	"access.db"

int
main()
{
	extern int errno;
	DB *dbp;

	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);
	}

As you can see, we're opening a database named access.db. The underlying database is a B+tree, and since we've specified DB_CREATE, we'll create it if it doesn't already exist. The mode of any files we create is 0664 (i.e., readable and writeable by the owner and the group, and readable by everyone else).

If the call to db_open is successful, the variable dbp will contain a database handle that will be used to access the underlying database.