NAME

ksql —

yet another SQLite wrapper

LIBRARY

library “ksql”

SYNOPSIS

#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

DESCRIPTION

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.

Database safety

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).

Compiling and linking

To compile with ksql, use the header file <ksql.h>. For linking, use -lksql -lsqlite3.

Access protocol

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).

Pledge Promises

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.

CAVEATS

This library is not thread-safe and does not plan to be.