SNKV API Reference

kvstore_open_v2

Open or create a database with full configuration control. Pass NULL for pConfig to use all defaults (WAL mode, NORMAL sync, 8 MB cache).

/* default open */
KVStore *kv;
kvstore_open_v2("mydb.db", &kv, NULL);

/* fully configured */
KVStoreConfig cfg = {0};
cfg.journalMode = KVSTORE_JOURNAL_WAL;
cfg.syncLevel   = KVSTORE_SYNC_FULL;
cfg.cacheSize   = 4000;
cfg.busyTimeout = 5000;
kvstore_open_v2("mydb.db", &kv, &cfg);

/* read-only */
KVStoreConfig ro = {0};
ro.readOnly = 1;
kvstore_open_v2("mydb.db", &kv, &ro);

KVSTORE_OK on success, error code otherwise.

kvstore_open

Simplified open. Equivalent to kvstore_open_v2 with only journalMode set; all other fields use defaults.

KVStore *kv = NULL;
kvstore_open("mydata.db", &kv, KVSTORE_JOURNAL_WAL);

kvstore_close

Close the database and free all resources. Any uncommitted transaction is rolled back. Runs a WAL checkpoint before closing.

kvstore_put

Insert or update a key-value pair. If the key already exists, its value is replaced. Keys and values are binary-safe. Without an explicit transaction, each call auto-commits.

kvstore_get

Retrieve a value by key. The returned buffer is heap-allocated by SNKV. Caller must free with sqliteFree() / snkv_free().

void *value = NULL; int vlen = 0;
int rc = kvstore_get(kv, "user:1", 6, &value, &vlen);
if (rc == KVSTORE_OK) {
    printf("%.*s\n", vlen, (char*)value);
    sqliteFree(value);
}

KVSTORE_OK if found · KVSTORE_NOTFOUND if key does not exist.

kvstore_delete

Delete a key. Returns KVSTORE_NOTFOUND if the key did not exist.

kvstore_exists

Check if a key exists without reading its value. More efficient than kvstore_get for existence checks. Sets *pExists to 1 if found, 0 otherwise.

kvstore_cf_create

Create a new column family. zName max 255 characters, must be unique. *ppCF receives the handle.

kvstore_cf_open

Open an existing column family. Returns KVSTORE_NOTFOUND if it does not exist.

kvstore_cf_get_default

Get a handle to the default column family. Always exists; created automatically on open.

kvstore_cf_drop

Delete a column family and all its data permanently. The default column family cannot be dropped. Also removes any hidden TTL index CFs.

kvstore_cf_list

List all column families. Caller must free each name and the array with sqliteFree().

char **names = NULL; int count = 0;
kvstore_cf_list(kv, &names, &count);
for (int i = 0; i < count; i++) {
    printf("%s\n", names[i]);
    sqliteFree(names[i]);
}
sqliteFree(names);

kvstore_cf_close

Release the column family handle. Does not delete data.

CF Key-Value Operations

Identical to the default-CF variants but take a KVColumnFamily* handle.

kvstore_iterator_create / kvstore_cf_iterator_create

Create a forward iterator for the default or a specific column family.

kvstore_iterator_first / next / eof

Position at first entry, advance to next, or test for end-of-sequence.

kvstore_iterator_key / value

Read the current key or value. Pointers are owned by the iterator — do not free them. Valid until the next next() or close() call.

KVIterator *it = NULL;
kvstore_iterator_create(kv, &it);
kvstore_iterator_first(it);
while (!kvstore_iterator_eof(it)) {
    void *key, *val; int klen, vlen;
    kvstore_iterator_key(it, &key, &klen);
    kvstore_iterator_value(it, &val, &vlen);
    printf("%.*s\n", klen, (char*)key);
    kvstore_iterator_next(it);
}
kvstore_iterator_close(it);

kvstore_iterator_close

Release the iterator and its cursor. Always call this when done.

KVIterator *it = NULL;
kvstore_prefix_iterator_create(kv, "user:", 5, &it);
/* already at first match — do NOT call first() */
while (!kvstore_iterator_eof(it)) {
    void *key; int klen;
    kvstore_iterator_key(it, &key, &klen);
    kvstore_iterator_next(it);
}
kvstore_iterator_close(it);

/* Full reverse scan */
KVIterator *it = NULL;
kvstore_reverse_iterator_create(kv, &it);
kvstore_iterator_last(it);
while (!kvstore_iterator_eof(it)) {
    void *key; int klen;
    kvstore_iterator_key(it, &key, &klen);
    kvstore_iterator_prev(it);
}
kvstore_iterator_close(it);

/* Reverse prefix — do NOT call last(), already positioned */
kvstore_reverse_prefix_iterator_create(kv, "user:", 5, &it);
while (!kvstore_iterator_eof(it)) {
    kvstore_iterator_prev(it);
}
kvstore_iterator_close(it);

kvstore_iterator_seek

Reposition the iterator without closing and reopening it.

• Forward iterator — seek to the first key >= (pKey, nKey).
• Reverse iterator — seek to the last key <= (pKey, nKey).

If the seek lands outside a prefix iterator’s prefix, the iterator immediately enters the eof state. Call kvstore_iterator_key / kvstore_iterator_next as usual after a successful seek.

/* forward: scan from "m" onwards */
KVIterator *it = NULL;
kvstore_iterator_create(kv, &it);
kvstore_iterator_seek(it, "m", 1);
while (!kvstore_iterator_eof(it)) {
    void *key; int klen;
    kvstore_iterator_key(it, &key, &klen);
    kvstore_iterator_next(it);
}
kvstore_iterator_close(it);

/* reverse: scan from "m" backwards */
kvstore_reverse_iterator_create(kv, &it);
kvstore_iterator_seek(it, "m", 1);
while (!kvstore_iterator_eof(it)) {
    kvstore_iterator_prev(it);
}
kvstore_iterator_close(it);

Explicit ACID transactions for batching operations atomically. Without an explicit transaction, each put/delete auto-commits. Wrapping bulk writes in a single transaction is significantly faster.

kvstore_begin(kv, 1);
kvstore_put(kv, "key1", 4, "val1", 4);
kvstore_put(kv, "key2", 4, "val2", 4);
kvstore_commit(kv);   /* both writes are atomic */

kvstore_put_ttl / kvstore_get_ttl

/* write key that expires in 30 minutes */
int64_t exp = kvstore_now_ms() + 30 * 60 * 1000;
kvstore_put_ttl(kv, "sess:abc", 8, token, tlen, exp);

/* read with lazy expiry */
void *val = NULL; int nVal = 0; int64_t rem = 0;
int rc = kvstore_get_ttl(kv, "sess:abc", 8, &val, &nVal, &rem);
if (rc == KVSTORE_OK) { /* rem = ms remaining */ sqliteFree(val); }

kvstore_ttl_remaining

kvstore_purge_expired

Scan the expiry index and delete all expired keys in one write transaction. O(expired keys) — uses sorted expire-time prefix to stop at first non-expired entry.

kvstore_cf_put_ttl / kvstore_cf_get_ttl

CF-level equivalents of kvstore_put_ttl / kvstore_get_ttl. Semantics are identical; the TTL indexes are created lazily per CF and are fully independent.

kvstore_cf_ttl_remaining

Return remaining TTL for a key in this column family without fetching the value. Return codes and *pnRemaining semantics are identical to kvstore_ttl_remaining.

kvstore_cf_purge_expired

Scan and delete all expired keys in this column family only, in a single write transaction. O(expired keys). Purging CF A never affects other column families.

kvstore_put_if_absent / kvstore_cf_put_if_absent

The existence check and the write are performed inside a single write transaction, so no other writer can insert the same key concurrently.

int inserted = 0;
kvstore_put_if_absent(kv, "lock", 4, "owner", 5, 0, &inserted);
if (inserted) {
    puts("acquired lock");
} else {
    puts("lock already held");
}

/* with TTL: session token that expires in 1 hour */
int64_t exp = kvstore_now_ms() + 3600 * 1000;
kvstore_put_if_absent(kv, session_id, sid_len, token, tok_len, exp, NULL);

kvstore_clear / kvstore_cf_clear

Truncates the column family’s B-tree in O(pages) time using SQLite’s BtreeClearTable — the B-tree structure (root page) is preserved so future inserts work immediately without re-opening.

/* flush a rate-limit namespace at midnight */
kvstore_cf_clear(rate_limit_cf);

/* wipe everything in the default CF */
kvstore_clear(kv);

kvstore_count / kvstore_cf_count

Counts only the main data B-tree of the column family. TTL index CFs are separate B-trees and are not included. Expired-but-not-yet-purged keys are included in the count — call kvstore_purge_expired first for an exact live count.

int64_t n;
kvstore_count(kv, &n);
printf("default CF has %lld entries\n", (long long)n);

kvstore_purge_expired(kv, NULL);
kvstore_count(kv, &n);
printf("live entries after purge: %lld\n", (long long)n);

kvstore_errmsg

Return the last error message string. Do not free. Valid until the next operation on the same handle.

kvstore_stats / kvstore_stats_reset

kvstore_stats fills the KVStoreStats struct. All counters are cumulative from open (or last reset). kvstore_stats_reset zeros them; nDbPages is a live gauge and is never zeroed.

kvstore_integrity_check

Walk the entire B-tree and verify structural integrity. Returns KVSTORE_OK or KVSTORE_CORRUPT with details in *pzErrMsg. Caller must free *pzErrMsg with sqliteFree().

kvstore_sync

Force all pending changes to disk. If a write transaction is active, performs a commit-and-reopen cycle to flush the WAL.

kvstore_incremental_vacuum

Reclaim unused pages and shrink the database file. Pass 0 to free all unused pages, or a positive nPage to limit work per call (good for latency-sensitive apps).

kvstore_incremental_vacuum(kv, 0);    /* free all */
kvstore_incremental_vacuum(kv, 50);   /* incremental: 50 pages */

kvstore_checkpoint

Copy WAL frames back into the main database file. pnLog and pnCkpt may be NULL. Requires no active write transaction. Non-WAL databases: no-op returning KVSTORE_OK.

int nLog = 0, nCkpt = 0;
kvstore_checkpoint(kv, KVSTORE_CHECKPOINT_PASSIVE, &nLog, &nCkpt);
printf("%d frames total, %d checkpointed\n", nLog, nCkpt);

/* reclaim WAL disk space */
kvstore_checkpoint(kv, KVSTORE_CHECKPOINT_TRUNCATE, NULL, NULL);