libcmdbm

A C99 SQL mapping library in the shape of MyBatis: statements live in XML mapper files, parameters and results are JSON objects, and the application never writes SQL text or binding code.

Objects are structs of function pointers

libcmdbm follows the convention of libcmutils, on which it is built. An object is a struct whose members are its methods, and every method takes the object as its first argument. The CMCall macro fills that argument in:

CMDBM_Session *sess = CMCall(ctx, GetSession);   // ctx->GetSession(ctx)
CMCall(sess, Close);                             // sess->Close(sess)

The three objects of an application

• CMDBM_Context - one per application. Reads the JSON configuration, owns the datasources declared in it and hands out sessions.
• CMDBM_Database - a datasource: one DBMS module, one connection pool and the mapper files whose statements it can run. Usually built from the configuration, but CMDBM_DatabaseCreate builds one in code.
• CMDBM_Session - the object statements are run through. One session borrows at most one connection per datasource and holds them until it is closed, which is what makes a transaction across several datasources possible.

Lifecycle

CMDBM_Init();                        // first library call in the process
ctx = CMDBM_ContextCreate("cmdbm_config.json", "UTF-8", NULL);
sess = CMCall(ctx, GetSession);
row = CMCall(sess, GetRow, "sales", "user.selectUser", params);
CMUTIL_JsonDestroy(row);             // results are owned by the caller
CMCall(sess, Close);                 // returns the connections to the pool
CMCall(ctx, Destroy);
CMDBM_Clear();                       // also clears libcmutils

Results handed out by a session are owned by the caller and are released with CMUTIL_JsonDestroy. The parameter object stays the caller's.

Where to look

Topics, in the bar above, groups the API by subject. Data Structures lists the object types, and the search box finds anything by name.

Elsewhere:

• Project page - the configuration file and the mapper syntax, neither of which is C API and so neither of which appears here, plus the same API in prose.
• Repository - source, issues and releases.
• Tests
  • runnable code, including a complete DBMS module written for the tests.