cl-berkeley-db

Introduction

This is a Common Lisp wrapper to the Berkeley DB library. It uses cffi and trivial-garbage. It's been tested on sbcl but should work on any distribution. There are a couple of functions that need to be implemented to make it work on other common-lisp implementations. This library has a BSD license.

The goal of this api is to support the latest version (currently 4.6) of the Berkeley DB library. There are other wrappers for earlier versions (Berkeley DB 4.3) (Berkeley DB 4.0).

API Implementation Matrix
section	Notes
Cursors	All methods start with cursor instead of c so c-get is cursor-get. There are also helper functions for the cursor get function such as cursor-get-first which is the same as cursor-get with the DB_FIRST flag set.
Databases	Each db type (btree,queue,hash,recno) has a cooresponding type in lisp and a constructor function of the same name. The following methods are not implemented (Contributions welcome) db-compact db-join db-key-range db-rename db-stat db-verify db-set-alloc (setf db-cache-size) (setf db-err-call) (setf db-msg-call) db-err-file (setf db-err-file) db-msg-file (setf db-msg-file)
Environments	The following methods are not implemented (Contributions welcome) (setf env-alloc) (setf env-cache-size) env-err-file (setf env-err-file) env-msg-file (setf env-msg-file) env-rpc-server
Key/Data Pairs	DBT's are divided into separate types with constructor functions of the same name: db-dbt Creates a dbt handle that berkeley-db can fill in. Usually used as a result of a get requests data-dbt Creates a dbt initialized with user supplied (unsigned-byte 8) data. buffer-dbt Used with get style requests with results stored in the user supplied buffer app-dbt Used where the user needs to supply the type of memory allocation.
Locking	Contributions welcome
Logging	Contributions welcome
Memory Pool	Contributions welcome
Mutexes	Contributions welcome
Replication	Contributions welcome
Sequences	Contributions welcome
Transactions

TODO

Ongoing

Improve documentation

For "1.0"

Expose all of the Berkeley DB library
Stabilize and standardize conventions for exposed api
Remove cl implementation specific code

Once "1.0" status is reached, the version will be bumped up to the version of the Berkeley DB library is. It will have the version berkeley-major.berkeley-minor.cl-berkeley-version. So for example for 4.5 it will be 4.5.0. The very minor version number for the berkeley library will be droped in our versions

Developer Notes

There are 2 api's. An internal one created by swig and an external one that is seen by the users. The swig generated interface covers 70% of the direct interface to the package. But Swig needs help in understanding some of the structures in db.h. It ignores constant declarations inside structure declarations. Also, it assumes that sub-structures (structure declarations inside other structure declarations) are pointers, causing alignment problems. For these reasons, interface files need to be created for structures that aren't translated correctly.

berkeley-db is "object oriented" in the sense that all structure instances have function pointers for thier methods. There are helper macros to allow the creation of these methods in lisp. The functions in berkeley-db are of 3 types:

functions with error codes
void functions
functions that return other types