cyrusdb API
***********


Intro
=====

The "cyrusdb" API is a common interface to a key-value store, used
throughout the Cyrus code. It allows a choice of different backends
for different access patterns, while ensuring a consistent interface.

This document will describe the interface, and how to use the cyrusdb
interface from within parts of Cyrus code, as well as how to implement
your own backend

If you pass incorrect values to these APIs, you will get an assertion
failure in most cases. That's generally considered safer than silently
breaking things. Exceptions are noted below.


Code Layout
===========

The implementation of each interface is in "lib/cyrusdb_NAME.c", for
example lib/cyrusdb_flat.c. General functions are in "lib/cyrusdb.c"
and the interface in "lib/cyrusdb.h".


Configuration
=============

The name of the backend for each of the main internal databases can be
configured in imapd.conf, for example: "annotation_db: skiplist". This
is then read in imap/global.h and imap/global.c during startup, so
that the global variable "config_annotation_db" gets set to the
configured backend name:

   config_annotation_db = config_getstring(IMAPOPT_ANNOTATION_DB);

(Beware the misleading naming here: "config_annotation_db" is a string
describing the *backend* used by the database, not, say, its location
on disk.)

Internally, the main module for each database sets up struct of
pointers to the cyrusdb functions it implements, which is registered
in "lib/cyrusdb.c"

"lib/cyrusdb.c" provides backend-agnostic wrapper functions for
interacting with cyrusdb databases.


A full example
==============

   struct db *db = NULL;
   struct txn *tid = NULL;
   const char *filename = NULL;
   int flags = CYRUSDB_CREATE;

   cyrus_init(alt_config, "toolname", 0);

   filename = config_getstring(IMAPOPT_ANNOTATION_DB_PATH);

   r = cyrusdb_open(config_annotation_db, filename, flags, &db);

   r = cyrusdb_fetch(db, key, keylen, &data, &datalen, &tid);

   r = cyrusdb_commit(db, tid);

   r = cyrusdb_close(db);

   cyrus_done();

Note that you always open a database first, and close it at the end.
You must always call cyrus_init() and cyrus_done() to properly
initialize and clean up the "cyrusdb" environments.

This example also uses a transaction, meaning that the database is
locked in exclusive mode between the 'fetch' (the first use of the
transaction) and the commit.


About Transactions
==================

The cyrusdb interface works in two modes - transactional and non-
transactional. The value of the 'tid' parameter decides which mode is
used. There are three possible values:

* NULL - non-transactional. Will create a temporary lock for the
  duration of the current action - either a write lock for "store" or
  a read lock for "fetch". If you call "foreach", the lock will be
  dropped between each record fetched

* Pointer to NULL - transactional, transaction not yet started. Will
  always take a write lock on the database, and update the pointer to
  point to the new transaction.

* Pointer to a valid transaction. Will keep using this transaction

If you are currently in a transaction, you MUST pass the same
transaction to every database call. It is not possible to mix or nest
transactions. There is one exception in the skiplist backend: *If you
pass NULL to a fetch or foreach while the database is in a
transaction, it will silently do the read in the current transaction
rather than returning an error*


API Reference
=============

All functions follow the normal C API of returning '0' on success, and
an error code on failure


cyrusdb_init(void)
------------------

Is called once per process. Don't call this yourself, use
"cyrus_init()". No other calls will be made until this is called.


cyrusdb_done(void)
------------------

The opposite of "cyrusdb_init()" - called once per process to do any
cleaning up after all database usage is finished. Don't call this
yourself, use "cyrus_done()".


cyrusdb_sync(const char *backend)
---------------------------------

Perform a checkpoint of the database environment. Used by berkeley
backend. Is called by "ctl_cyrusdb -c" on a regular basis


cyrusdb_open(const char *backend, const char *fname, int flags, struct db **retdb)
----------------------------------------------------------------------------------

Opens the database with the specified 'file name' (or other
descriptor, for example the sql backend is not a filename), and if
successful returns an opaque database structure

Flags:

* CYRUSDB_CREATE - create the database if it doesn't exist

* CYRUSDB_MBOXSORT - sort '.' first, so folder listing is correct

Errors:

* CYRUSDB_IOERROR - if there is any error reading the file, or any
  corruption detected while loading the file


cyrusdb_close(struct db *db)
----------------------------

Close the named database. Will release any locks if they are still
held, but it's bad practice to close without committing or aborting,
so the backend should log an error

Errors:

* CYRUSDB_IOERROR - if there are any errors during close


cyrusdb_fetch(struct db *db, const char *key, size_t keylen, const char **data, size_t *datalen, struct txn **tidptr)
---------------------------------------------------------------------------------------------------------------------


cyrusdb_fetchlock(struct db *db, const char *key, size_t keylen, const char **data, size_t *datalen, struct txn **tidptr)
-------------------------------------------------------------------------------------------------------------------------

Fetch the value for the exact key given by key and keylen. If data is
not NULL, set datalen and return a valid pointer to the start of the
value.

Fetchlock is identical to fetch, but gives a hint to the database that
the record is likely to be modified soon.

NOTE: it is possible to store a key with a zero length data record, in
which case *datalen will be set to zero, and *data will be set to a
non-NULL value

It is an error to call fetch with a NULL key or a zero keylen

It is an error to call fetch with a NULL datalen and a non-NULL data,
however it is acceptable to call with a NULL data and a non-NULL
datalen if you are only interested in the length

Errors:

* CYRUSDB_IOERROR - if any error occurs reading from the database

* CYRUSDB_LOCKED - if tidptr is incorrect

* CYRUSDB_NOTFOUND - if there is no record that matches the key


cyrusdb_foreach(struct db *db, const char *prefix, size_t prefixlen, foreach_p *goodp, foreach_p *procp, void *rock, struct txn **tidptr)
-----------------------------------------------------------------------------------------------------------------------------------------


cyrusdb_forone(struct db *db, const char *key, size_t keylen, foreach_p *goodp, foreach_p *procp, void *rock, struct txn **tidptr)
----------------------------------------------------------------------------------------------------------------------------------

"cyrusdb_foreach()" iterates over all records matching the given
prefix, in database order (which may be MBOXLIST sort, depending on
the parameters given to open

It is legal to give a NULL pointer as prefix if prefixlen is zero, in
which case it will return all records in the database. It is an error
to give a non-zero prefixlen with a NULL prefix.

"cyrusdb_forone()" "iterates" over the single record matched by the
given key. If you've already built callbacks for processing each
record from a foreach, this lets you use the same interface to process
a single record.

"goodp" - this function is only used for deciding if the record needs
to be further processed. It can be used for basic filtering, and
returns true (non-zero) to process, or zero to skip and move straight
to the next record. Because goodp can't make any database changes, it
doesn't break the lock, so it's faster to use goodp to filter records
if you don't need to process all of them. NULL is a legal value for
goodp, and means that all records will be processed.

"procp" - procp is the main callback function. If you use foreach in
non-transactional mode, the database is unlocked before calling procp,
and locked again afterwards. You are allowed to add, delete or modify
values in the same database from within procp. If procp returns non-
zero, the foreach loop breaks at this point, and the return value of
the foreach becomes the return value of procp. If procp returns zero,
the foreach loop will continue at the NEXT record by sort order,
regardless of whether the current record has changed or been removed.
procp MUST NOT be NULL.

Errors:

* procp_result - whatever your callback returns

* CYRUSDB_IOERROR - if any error occurs while reading

* CYRUSDB_LOCKED - if tidptr is incorrect


cyrusdb_create(struct db *db, const char *key, size_t keylen, const char *data, size_t datalen, struct txn **tidptr)
--------------------------------------------------------------------------------------------------------------------


cyrusdb_store(struct db *db, const char *key, size_t keylen, const char *data, size_t datalen, struct txn **tidptr)
-------------------------------------------------------------------------------------------------------------------

Create a new record or replace an existing one. The only difference
between these two is that "cyrusdb_create" will return an error if the
record already exists, while "cyrusdb_store" will replace it

If tidptr is NULL, create/store will take a write lock for the
duration of the action.

Any failure during create/store will abort the current transaction as
well as returning an error

It is legal to pass NULL for the data field ONLY if datalen is zero.
It is not legal to pass NULL for key or zero for keylen

Errors:

* CYRUSDB_IOERROR - any error to write to the database

* CYRUSDB_LOCKED - if tidptr is incorrect

* CYRUSDB_EXISTS - if "cyrusdb_create" is called on an existing key

* CYRUSDB_AGAIN - if a deadlock is created. The current transaction
  has been aborted, but a retry may succeed


cyrusdb_delete(struct db *db, const char *key, size_t keylen, struct txn **tidptr, int force)
---------------------------------------------------------------------------------------------

Delete the given record from the database. If force is true, then
succeed even if the record doesn't currently exist.

It is not legal to pass NULL for key or zero for keylen

Errors:

* CYRUSDB_IOERROR - any error to write to the database

* CYRUSDB_LOCKED - if tidptr is incorrect

* CYRUSDB_NOTFOUND - if force is not set and the key doesn't exist

* CYRUSDB_AGAIN - if a deadlock is created. The current transaction
  has been aborted, but a retry may succeed


cyrusdb_commit(struct db *db, struct txn *tid)
----------------------------------------------

Commit the current transaction. tid will not be valid after this call,
regardless of success

If the commit fails, it will attempt to abort the transaction

Errors:

* CYRUSDB_IOERROR - any error to write to the database

* CYRUSDB_LOCKED - if tidptr is incorrect

* CYRUSDB_AGAIN - if a deadlock is created. The current transaction
  has been aborted, but a retry may succeed


cyrusdb_abort(struct db *db, struct txn *tid)
---------------------------------------------

Abort the current transaction. tid will not be valid after this call,
regardless of success

Attempt to roll back all changes made in the current transaction.

Errors:

* CYRUSDB_IOERROR - any error to write to the database

* CYRUSDB_LOCKED - if tidptr is incorrect


cyrusdb_dump(struct db *db, int detail)
---------------------------------------

Optional function to dump the internal structure of the database to
stdout for debugging purposes. Don't use.


cyrusdb_consistent(struct db *db)
---------------------------------

Check if the DB is internally consistent. Looks pretty bogus, and
isn't used anywhere. Don't use.
