ksql —
yet another SQLite wrapper
library “ksql”
#include
<sys/types.h>
#include
<stdint.h>
#include
<ksql.h>
#define KSQL_VMAJOR x
#define KSQL_VMINOR y
#define KSQL_VBUILD z
#define KSQL_VERSION x.y.z
#define KSQL_VSTAMP xxxyyyzzz
The
ksql library is a “lazy
man's” wrapper of a minimal subset of the SQLite C API. It makes
interfacing with SQLite easy and fast for you, and safe for your database.
The typical usage scenario is as follows:
- assign configuration defaults with
ksql_cfg_defaults(3) and pre-set SQL
statements in the stmts array;
- allocate a handle with ksql_alloc_child(3)
or, for reduced security, ksql_alloc(3);
- open a database connection on that handle with
ksql_open(3);
- create statements with ksql_stmt_alloc(3) and
use them with ksql_bind_double(3),
ksql_stmt_double(3), and
ksql_stmt_free(3); or
- execute statements with ksql_exec(3);
- close and free with ksql_free(3).
There's also support for maintaining transactional consistency with
ksql_trans_open(3) and
ksql_trans_commit(3). Invoke “apropos
ksql” to see all functions.
The current version of the database is defined in
KSQL_VERSION as a string of major number,
minor number, and build. These values are available seperately as
KSQL_VMAJOR,
KSQL_VMINOR, and
KSQL_VBUILD, respectively. A numeric
concatenation of the version is defined as
KSQL_VSTAMP, which may be used to test for
version number applicability.
By default (see
ksql_alloc(3) and
ksql_alloc_child(3)), the library will invoke
exit(3) if any of the database functions fail.
“Failure” means that any SQLite function (for example, stepping
for result rows or binding parameters) that fails will trigger exit.
It will also register an
atexit(3) hook that will
clean up any open database connections, transactions, and open statements.
Lastly, it will intercept the
SIGABRT and
SIGSEGV and trigger a controlled exit.
Thus, if your program is signalled while performing (say) transactions, or any
sort of open database, you won't corrupt the data.
All of these safety measures can be disabled by providing the appropriate flags
to
ksql_alloc(3) or
ksql_alloc_child(3).
To compile with
ksql, use the header file
<ksql.h>.
For linking, use
-lksql
-lsqlite3.
Since SQLite uses a busy-wait approach,
ksql
will sleep for random intervals between attempts returning
SQLITE_BUSY or
SQLITE_LOCKED. Within the first 10
attempts, the random interval is within 1/4 second. Within the 10–100
attempts, within 1/10 second. Greater than 100 attempts, 1/100 second. This
scheme benefits longer waiters.
Functions using this algorithm are
ksql_exec(3),
ksql_stmt_step(3) and
ksql_stmt_cstep(3), and
ksql_stmt_alloc(3).
The
ksql library is built to operate in
security-sensitive environments, including
pledge(2) on
OpenBSD.
If running in single-process mode (i.e., with
ksql_alloc(3)), the
stdio rpath cpath wpath flock fattr pledges
are required for all functions.
If in split-process mode (with
ksql_alloc_child(3)), then
stdio rpath cpath wpath flock proc fattr is
required for
ksql_alloc_child(3), and only
stdio otherwise.
ksql_alloc(3),
ksql_alloc_child(3),
ksql_bind_blob(3),
ksql_bind_bytes(3),
ksql_bind_double(3),
ksql_bind_int(3),
ksql_bind_str(3),
ksql_bind_zblob(3),
ksql_cfg_defaults(3),
ksql_close(3),
ksql_exec(3),
ksql_free(3),
ksql_lastid(3),
ksql_open(3),
ksql_role(3),
ksql_stmt_alloc(3),
ksql_stmt_blob(3),
ksql_stmt_bytes(3),
ksql_stmt_cstep(3),
ksql_stmt_double(3),
ksql_stmt_free(3),
ksql_stmt_int(3),
ksql_stmt_isnull(3),
ksql_stmt_reset(3),
ksql_stmt_step(3),
ksql_stmt_str(3),
ksql_trans_commit(3),
ksql_trans_exclopen(3),
ksql_trans_functions(3),
ksql_trans_open(3),
ksql_trans_rollback(3),
sqlite3(3)
This library is not thread-safe and does not plan to be.