DB3 — Database Library

A C11 database library providing free-space management, B-tree indexes, and a multi-keyed record-based file. The API is modelled after the Sculptor database system.

Portability note: database files are written in host byte order. A file created on a little-endian machine cannot be read on a big-endian machine and vice versa. See CHANGELOG.md for details.

Features

• Multi-key records — up to 5 independent B-tree indexes per file
• Cursor traversal — knext / kprev in key order, kseekkey for positioned access
• Thread safety — concurrent access to different units; no global mutable state
• Portable fixed-width layout — int64_t offsets, int32_t counts (SUB_VER 4)
• Error handler hook — replace the default abort() with db3_set_error_handler
• C++ compatible — extern "C" declarations in db3.h

Layers

1. Free space manager (free/) — variable-size block allocator on a raw file
2. B-tree (btree/) — sorted index mapping fixed-width keys to file offsets
3. Multi-key file (mkf/) — record database built on the two layers above
4. Text store (text/) — variable-length string store (not integrated with mkf)

See ARCHITECTURE.md for a full description of each layer, on-disk formats, threading model, and key constraints.

Building

Requires CMake ≥ 3.16 and a C11 compiler.

cmake -B build -S .
cmake --build build
ctest --test-dir build --output-on-failure

Install (default prefix /usr/local):

cmake --install build

After install, link with:

pkg-config --cflags --libs db3

Quick example

#include <db3/db3.h>
#include <stdint.h>
#include <string.h>
#include <stdio.h>

int main(void) {
    int32_t keys = 1, keylen = 8, reclen = 16;

    /* Create and open a database on unit 1 */
    kopen(1, "mydb.dat", KF_CREAT, &keys, &keylen, &reclen);

    /* Insert — buf layout: [key (8 bytes)][data (16 bytes)] */
    char buf[24];
    memcpy(buf,     "MYKEY001", 8);
    memcpy(buf + 8, "application data    ", 16);
    kinsert(1, buf, buf);

    /* Read it back */
    char rbuf[24];
    memcpy(rbuf, "MYKEY001", 8);
    kread(1, 0, rbuf, rbuf);
    printf("data: %.16s\n", rbuf + 8);

    kclose(1);
    return 0;
}

See examples/ for a bulk-loader demo.

Limits

Parameter	Limit
Open units	17
Keys per file	5
Max key length	128 bytes
On-disk byte order	Host-endian (not cross-platform)

Changelog

See CHANGELOG.md. The current on-disk format is SUB_VER 4; files from v1.0–v1.3 are not compatible.

License

MIT. Copyright © 2006–2026 Base Information Systems.