.\" Copyright (c) 2009-2022 Julien Nadeau Carriere <vedge@csoft.net>
.\" All rights reserved.
.\"
.\" Redistribution and use in source and binary forms, with or without
.\" modification, are permitted provided that the following conditions
.\" are met:
.\" 1. Redistributions of source code must retain the above copyright
.\"    notice, this list of conditions and the following disclaimer.
.\" 2. Redistributions in binary form must reproduce the above copyright
.\"    notice, this list of conditions and the following disclaimer in the
.\"    documentation and/or other materials provided with the distribution.
.\" 
.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND ANY EXPRESS OR
.\" IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
.\" WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT,
.\" INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
.\" (INCLUDING BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
.\" SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT,
.\" STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING
.\" IN ANY WAY OUT OF THE USE OF THIS SOFTWARE EVEN IF ADVISED OF THE
.\" POSSIBILITY OF SUCH DAMAGE.
.\"
.Dd December 21, 2022
.Dt AG_DB 3
.Os Agar 1.7
.Sh NAME
.Nm AG_Db
.Nd agar key/value database access object
.Sh SYNOPSIS
.Bd -literal
#include <agar/core.h>
.Ed
.Sh DESCRIPTION
.Nm
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).
.\" MANLINK(AG_Dbt)
.Pp
Many of the functions described below accept Berkeley DB style
.Ft AG_Dbt
arguments.
This structure is defined as:
.Bd -literal
.\" SYNTAX(c)
typedef struct ag_dbt {
	void   *data;		/* Pointer to key or data */
	AG_Size size;		/* Key/data size (bytes) */
} AG_Dbt;
.Ed
.Sh INHERITANCE HIERARCHY
.Xr AG_Object 3 ->
.Nm .
.Sh INTERFACE
.nr nS 1
.Ft "AG_Db *"
.Fn AG_DbNew "const char *backend"
.Pp
.Ft "int"
.Fn AG_DbOpen "AG_Db *db" "const char *path" "Uint flags"
.Pp
.Ft "void"
.Fn AG_DbClose "AG_Db *db"
.Pp
.Ft "int"
.Fn AG_DbExists "AG_Db *db" "const AG_Dbt *key"
.Pp
.Ft "int"
.Fn AG_DbDel "AG_Db *db" "const AG_Dbt *key"
.Pp
.Ft "int"
.Fn AG_DbGet "AG_Db *db" "const AG_Dbt *key" "AG_Dbt *val"
.Pp
.Ft "int"
.Fn AG_DbPut "AG_Db *db" "const AG_Dbt *key" "const AG_Dbt *val"
.Pp
.Ft "int"
.Fn AG_DbSync "AG_Db *db"
.Pp
.nr nS 0
The
.Fn AG_DbNew
function creates a new
.Nm
object instance.
The
.Fa backend
argument specifies the database backend to use.
Available backends include:
.Bl -tag -compact -width "mysql "
.It hash
Extended Linear Hashing (Berkeley DB)
.It btree
Sorted, Balanced Tree Structure (Berkeley DB)
.It mysql
MySQL database storage
.El
.Pp
The
.Fn AG_DbOpen
function opens the database for further access.
The
.Fa 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).
.Pp
The
.Fn AG_DbClose
function closes the database.
.Pp
The
.Fn AG_DbExists
function returns 1 if the given key matches an entry in the database,
or 0 if no match was found.
.Pp
The
.Fn AG_DbDel
function deletes the named entry associated with
.Fa key .
.Pp
The
.Fn AG_DbGet
function retrieves the database entry referenced by the specified key.
The data is returned as newly-allocated memory in
.Fa val ,
and must be freed after use.
It is not necessary to initialize the supplied
.Fa val
argument.
.Pp
The
.Fn AG_DbPut
function writes the specified database entry.
.Pp
.Fn AG_DbSync
synchronizes the actual contents of
.Fa db
with any associated database files.
.Sh EXAMPLES
The following code creates a new database or accesses the existing database
.Pa my.db ,
checks whether a record exists under "mykey" and if not, create one containing
the string "myval".
.Bd -literal -offset indent
.\" SYNTAX(c)
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);
.Ed
.Sh SEE ALSO
.Xr AG_Intro 3 ,
.Xr AG_Object 3
.Sh HISTORY
The
.Nm
interface first appeared in Agar 1.5.0.