loxdb

Predictable-memory database for microcontrollers. KV + time-series + relational, one malloc, WAL recovery.

CI Language: C99 License: MIT Platform: MCU | Linux | Windows | macOS Tests Release

• GitHub "Source code (zip/tar.gz)" assets are automatic tag snapshots (source tree).
• loxdb-source-vX.Y.Z.zip is the explicit source distribution asset (source + tests + tooling).
• loxdb-sdk-vX.Y.Z-<platform>.(zip|tar.gz) assets are install-prefix SDK bundles (headers + libraries + CMake package files) and are not expected to include src/*.c.

loxdb is a compact embedded database written in C99 for firmware and small edge runtimes. It provides one unified API over three engines (KV, time-series, relational) and is designed around predictable memory behavior. The library allocates once at lox_init() and runs without allocator churn during normal operation. Persistence is optional via a small storage HAL (read/write/erase/sync), with WAL + recovery when enabled.

Test suite size: 504 microtest cases across 48 test files (+1 C++ wrapper test), organized into ~78 CTest entries including RAM-budget sweep matrices.

#include "lox.h"
#include "lox_port_ram.h"
int main(void) {
 lox_t db;
 lox_storage_t storage;
 lox_cfg_t cfg = {0};
 if (lox_port_ram_init(&storage, 64u * 1024u) != LOX_OK) return 1;
 cfg.storage = &storage;
 cfg.ram_kb = 32u;
 if (lox_init(&db, &cfg) != LOX_OK) {
 lox_port_ram_deinit(&storage);
 return 1;
 }
 uint8_t v = 7u, out = 0u;
 size_t out_len = 0u;
 if (lox_kv_put(&db, "k", &v, sizeof(v)) != LOX_OK) {
 lox_deinit(&db);
 lox_port_ram_deinit(&storage);
 return 1;
 }
 if (lox_kv_get(&db, "k", &out, sizeof(out), &out_len) != LOX_OK) {
 lox_deinit(&db);
 lox_port_ram_deinit(&storage);
 return 1;
 }
 lox_deinit(&db);
 lox_port_ram_deinit(&storage);
 return 0;
}

cmake --preset ci-debug-linux
cmake --build --preset ci-debug-linux
ctest --preset ci-debug-linux

• KV (key-value): config/state, binary-safe values, optional TTL, bounded by compile-time limits.
• TS (time-series): typed telemetry streams (F32/I32/U32/RAW) with timestamp range queries and retention policies.
• REL (relational): small fixed-schema tables with one indexed column, designed for predictable memory use.

loxdb is written in portable C99 and works on any MCU with byte-write flash storage — including ESP32 family, STM32, RP2040, nRF52, and similar Cortex-M class hardware. Only platforms verified end-to-end on real hardware are listed below; ports to other targets are technically supported but not yet bench-validated.

Verified using the ESP32-S3 bench runners under bench/. Published benchmark results live in docs/BENCHMARKS.md (template until filled with real measurements).

• Current release line: v1.4.0 (see CHANGELOG.md).
• Young project focused on embedded correctness and predictable memory behavior; production use-cases and feedback are welcome.

This repository is the MIT-licensed OSS edition. A planned commercial edition (loxdb_pro) will live in a separate repository as additive modules on top of loxdb (it will not replace or relicense the MIT core). See docs/EDITIONS.md.

• Getting started: docs/GETTING_STARTED_5_MIN.md
• Programmer manual: docs/PROGRAMMER_MANUAL.md
• Backend integration: docs/BACKEND_INTEGRATION_GUIDE.md
• Port authoring (ESP32 reference): docs/PORT_AUTHORING_GUIDE.md
• Schema migration: docs/SCHEMA_MIGRATION_GUIDE.md
• Docs index: docs/README.md

• Contributing guide: .github/CONTRIBUTING.md
• Support policy: .github/SUPPORT.md
• Security policy: .github/SECURITY.md

MIT (see LICENSE).