LOX · EMBEDDED STORAGE / C99

LOX DB

Three small data models, one predictable storage core.

A compact C99 database for firmware and edge runtimes: key-value state, timestamped telemetry and small fixed-schema tables share one API and an optional storage abstraction. Memory bounds and persistence behavior are explicit design inputs.

Stablev1.5.3MITC99595 microtests documented
Source and releasesExplore the engines

Available through PlatformIO Registry and Arduino Library Manager. Integration remains target and adapter specific.

LOX DB engine and persistence architectureAn application uses one public API to select key-value, time-series, or relational engines. The engines use bounded in-memory arenas and can persist through a storage HAL with optional write-ahead logging and reopen recovery.PUBLIC C APIKVTIME SERIESRELATIONALOPTIONAL WAL + RECOVERYSTORAGE HAL
  • Application API
  • KV · TS · REL engines
  • Optional WAL and recovery
  • Storage HAL
01 / THREE DATA MODELS

Choose a shape that fits the firmware

LOX DB puts several bounded data models behind one C interface. Each remains deliberately narrower than a server database: callers size storage and choose policies for their workload.

ENGINE 01

Key-value

Binary-safe values for configuration and application state, bounded by configured key and value limits. Optional TTL and compile-time overflow policy shape behavior at capacity.

ENGINE 02

Time-series

Typed streams for F32, I32, U32 and raw samples, with timestamp range queries and retention/overflow policies. Packed samples pair timestamps with values. The TS arena is divided evenly among configured stream slots, so mixed types do not use every byte equally efficiently.

ENGINE 03

Relational

Small fixed-schema tables with explicit schema declarations, row helpers and one indexed column per table. This is a compact record model, not general SQL planning or arbitrary joins.

One handle, explicit setup. lox_init() validates configuration and storage, creates internal arenas and loads durable state when storage is supplied. Normal engine operations do not churn the core allocator after successful initialization; ports and user callbacks have their own allocation behavior.
02 / MEMORY MODEL

Bounded arenas, one core allocation

The database targets MCU and edge systems where memory must be budgeted before normal work begins. Configuration chooses the main RAM budget and engine capacities. The core makes one main heap allocation during initialization and releases it at lox_deinit().

This statement is scoped to the core. Platform adapters, storage callbacks and application code may allocate independently. A bounded database arena does not bound total firmware memory unless those components are budgeted too.

Handles may be several KiB; the manual recommends keeping potentially large lox_t objects off small task stacks. Review profile and footprint gates for the exact build configuration.

INITIALIZATION
validate config + HAL
↓
one core arena allocation
↓
load snapshot / recover WAL
↓
steady-state engine calls
no core allocator churn on normal operations
03 / STORAGE ABSTRACTION

The media contract is a small HAL

Persistence is optional. A storage adapter supplies read, write, erase and sync callbacks through lox_storage_t. The abstraction lets the core work with RAM-backed and platform-backed media while keeping erase geometry and write constraints visible at initialization.

CALLERApplication mutationKV, TS, REL or transaction API
COREEngine statebounded in-memory structures
OPTIONALWAL / snapshotenabled by build and configuration
PORTStorage callbacksread · write · erase · sync

Repository ports cover RAM and POSIX use, an ESP32 path, and optional backend adapters. A port is an integration surface: durability and electrical properties depend on its implementation and physical medium.

04 / WAL AND REOPEN

Recovery is a defined path, not a hardware guarantee

When WAL support is enabled with persistent storage, reopening validates durable state and applies documented recovery rules. The manual describes replay, handling recoverable WAL tails and compaction. Some anomalies can return success with recovery performed; success does not mean no anomaly occurred.

LOX DB mutation and reopen sequenceA mutation reaches the selected engine and persistence path. On reopen, the core reads durable state, evaluates the snapshot and WAL, handles a recoverable tail according to documented rules, then restores state.MUTATIONENGINE STATEWAL / SNAPSHOTREOPEN SCANRESTORED STATERECOVERABLE TAIL HANDLING ≠ PHYSICAL POWER-LOSS VALIDATION
  1. Application mutation reaches an engine
  2. Configured persistence records durable state
  3. Reopen scans snapshot and WAL
  4. Documented replay or recoverable-tail handling restores state

What this evidence does not establish

The published ESP32-S3 benchmark uses an in-RAM flash-like storage backend. It measures target CPU work and logical backend operations, not physical NOR latency, brownout recovery, erase endurance or board-level power-loss behavior.

05 / PORTS AND PACKAGING

Core, adapters and distribution have separate jobs

Core library

The core is portable C99 with no required third-party runtime library. CMake exports an installable package as loxdb::loxdb; detached C and C++ consumer checks exercise installed-package use. A C++ convenience wrapper is separate from the C API.

Target integrations

RAM and POSIX ports, an ESP32 path and optional backend adapters cover different environments. Arduino and PlatformIO manifests publish the library through their registries. Hardware- or filesystem-specific behavior still depends on the chosen adapter and board.

RAM PORT · CAPI SKETCH
static lox_t db; /* keep the handle off a small stack */
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) return 1;
uint8_t value = 7u;
if (lox_kv_put(&db, "mode", &value, sizeof value) != LOX_OK) return 1;
06 / VERIFICATION AND MEASUREMENTS

Evidence is recorded by environment

HOST EXECUTEDWindows test lanes

The current evidence matrix records MSVC Debug at 110/110 CTest entries, MinGW Debug at 110/110 and Release at 111/111, and Clang MinGW-target Debug/Release at those respective counts.

STATIC ANALYSISCore checks

The matrix records cppcheck warning/performance/portability and clang-tidy analyzer, bugprone, performance and portability checks passing locally.

MEASUREDESP32-S3 CPU + RAM backend

The repository publishes timings and throughput from an ESP32-S3 N16R8 run backed by an in-RAM flash-like HAL. These are target measurements, not physical-flash results.

NOT EXECUTED HEREPhysical-media claims

The evidence matrix reports no physical NOR sync/write/erase, brownout or endurance evidence. Linux/macOS and sanitizer CI lanes are configuration, not host-execution evidence.

Evidence matrixBenchmark notesTest suite counts

07 / BUILD PATH

Build, test and inspect the installed surface

The repository's documented desktop path uses a CMake preset and CTest. Preset availability depends on the host platform.

DESKTOP · CMAKE
cmake --preset ci-debug-linux
cmake --build --preset ci-debug-linux
ctest --preset ci-debug-linux

For installed consumers, the package exports loxdb::loxdb and generated CMake package/version files. Source archives and install-prefix SDK bundles have different contents; consult the current README and release assets when packaging a deployment.

08 / FIT AND BOUNDARIES

Where LOX DB is a good fit

Use the shape deliberately

  • It targets bounded embedded/edge data, not general SQL flexibility, advanced indexing or unbounded queries.
  • Relational tables are fixed-schema and support one indexed column per table.
  • There is no server-style multi-process concurrency model or transparent large-object storage.
  • The one-allocation statement describes the core after initialization, not adapters or callbacks.
  • WAL recovery tests and RAM-backed benchmarks do not establish physical flash, brownout or endurance behavior.

LOX DB Pro is a separate product in the LOX family. Its product page defines its own scope; this page describes the open-source LOX DB repository.

LOX DB Pro · LOX family · All products