NAME

AG_Db — agar key/value database access object

SYNOPSIS

#include <agar/core.h>

DESCRIPTION

AG_Db provides a simple interface for accessing databases of key/value pairs. Various database backends are implemented, such as "hash", "btree" and "mysql". Different backends may support different key types (e.g., raw data, C strings or record numbers).

Many of the functions described below accept Berkeley DB style AG_Dbt arguments. This structure is defined as:

typedef struct ag_dbt {
	void   *data;		/* Pointer to key or data */
	AG_Size size;		/* Key/data size (bytes) */
} AG_Dbt;

INHERITANCE HIERARCHY

AG_Object(3) -> AG_Db.

INTERFACE

AG_Db *
AG_DbNew(const char *backend);

int
AG_DbOpen(AG_Db *db, const char *path, Uint flags);

void
AG_DbClose(AG_Db *db);

int
AG_DbExists(AG_Db *db, const AG_Dbt *key);

int
AG_DbDel(AG_Db *db, const AG_Dbt *key);

int
AG_DbGet(AG_Db *db, const AG_Dbt *key, AG_Dbt *val);

int
AG_DbPut(AG_Db *db, const AG_Dbt *key, const AG_Dbt *val);

int
AG_DbSync(AG_Db *db);

The AG_DbNew() function creates a new AG_Db object instance. The backend argument specifies the database backend to use. Available backends include:

hash

Extended Linear Hashing (Berkeley DB)

btree

Sorted, Balanced Tree Structure (Berkeley DB)

mysql

MySQL database storage

The AG_DbOpen() function opens the database for further access. The path argument is backend-specific. With "hash" and "btree, it may be a file name. With "mysql", it may be set to a database name (or set to NULL to use the default database settings).

The AG_DbClose() function closes the database.

The AG_DbExists() function returns 1 if the given key matches an entry in the database, or 0 if no match was found.

The AG_DbDel() function deletes the named entry associated with key.

The AG_DbGet() function retrieves the database entry referenced by the specified key. The data is returned as newly-allocated memory in val, and must be freed after use. It is not necessary to initialize the supplied val argument.

The AG_DbPut() function writes the specified database entry.

AG_DbSync() synchronizes the actual contents of db with any associated database files.

EXAMPLES

The following code creates a new database or accesses the existing database my.db, checks whether a record exists under "mykey" and if not, create one containing the string "myval".

AG_Db *db;
AG_Dbt dbtKey, dbtVal;
char key[8];

if ((db = AG_DbNew("btree")) == NULL)
	AG_FatalError(NULL);

if (AG_DbOpen(db, "my.db", 0) != 0)
	AG_FatalError(NULL);

dbtKey.data = "mykey";
dbtKey.size = 5;
if (!AG_DbExists(db, &dbtKey)) {
	dbtVal.data = "myval";
	dbtVal.size = 5;
	if (AG_DbPut(db, &dbtKey, &dbtVal)) != 0)
		AG_Verbose("Put failed (%s)\n", AG_GetError());
}

AG_DbClose(db);
AG_ObjectDestroy(db);

SEE ALSO

AG_Intro(3), AG_Object(3)

HISTORY

The AG_Db interface first appeared in Agar 1.5.0.