LibreDB — Embeddable Multi-Model Database

The Challenge

Embedded databases ask developers to accept a black box. You get durability guarantees you cannot inspect, query costs you cannot predict, and a codebase far too large to read. Teams that only need a real store for tests and local development end up either mocking their data layer — and shipping bugs that only a real database would have caught — or standing up three separate systems to cover key-value, document and relational shapes. We built LibreDB on one idea: a database can be powerful and still be understood by opening its source. The whole engineering budget in v1 goes to comprehension and provable durability rather than raw throughput.

Our Approach

One core, three lenses: A single ordered key-value kernel handles storage, transactions and durability. The key-value, document and relational APIs are thin typed lenses over that one core — FoundationDB-style — not three engines bolted together. A relational table is physically a document collection, which is physically ordered key-value entries built from composite keys. The result is that raw strings, JSON documents and schema-validated typed tables can live in the same database, even the same file.

Readable by design: The kernel is one file of under a thousand lines, roughly half of it explanatory prose. That is a deliberate product decision, not a limitation: the codebase is meant to be opened and read by anyone who wants to learn how a database actually works, and small enough that a contributor can reason about the whole durability path in one sitting.

Durability you can verify: A transaction that returns has been written to a length-framed, CRC-32-checksummed write-ahead log and fsync'd before the commit becomes visible. Failure modes outside the clean-crash model are handled explicitly rather than assumed away: a failed append or fsync latches the database instead of writing past a torn record, a second writer is refused by an exclusive open lock, a foreign file is refused untouched via a magic header, and mid-log corruption refuses to open rather than silently truncating. The crash and recovery path is proven by deterministic simulation testing — the real engine run against a seeded in-memory filesystem that tears, corrupts, errors and crashes the log on command — plus binary round-trip fuzzing, on top of 100% line coverage of the core.

Embeddable anywhere: The package ships zero runtime dependencies, is ESM-only and tree-shakeable at under 6 kB min+brotli, and carries its own TypeScript types. It runs in-memory for tests or file-backed for durability, targets Bun and Node 22+, and is published to npm, JSR and the CDNs. A dedicated browser entry imports nothing from node:, so it bundles cleanly for the web — with an injectable filesystem seam that backs durable storage onto an OPFS sync access handle inside a Web Worker.

Tooling: A libredb command-line tool inspects and edits .libredb files directly — namespaces, table schemas, key scans, atomic bulk import — with read commands opening the file read-only and write commands taking an advisory lock that refuses a second concurrent writer. It ships as a bin in the package, as self-contained binaries for Linux, macOS and Windows attached to each release with SHA-256 checksums, and as a multi-arch container image on both GHCR and Docker Hub.

Honest scope: LibreDB is an early beta whose recommended home today is test and development data. Queries are O(n) scans by design in v1, there are no secondary indexes yet, and access is embedded, in-process and strictly single-writer. These are documented v1 boundaries rather than hidden gaps, published alongside the performance envelope so nobody deploys it into a role it does not yet fill. Secondary indexes, a richer query surface and write-ahead log compaction are the next milestones.

Results

• 100% line, function and statement coverage on the core, with a passing SonarCloud quality gate
• Crash recovery proven by a deterministic simulation testing harness with IO-fault injection and binary fuzzing, not just asserted
• Zero runtime dependencies, ESM-only, under 6 kB min+brotli with TypeScript types included
• Published to npm and JSR, served by the public CDNs, with multi-arch CLI images on GHCR and Docker Hub and signed standalone binaries on every release
• One of three products in the LibreDB family, sharing an access-model spine with LibreDB Studio and the managed LibreDB Platform
• Commercial support and integration services for LibreDB are offered by Sekoya Grup Bilisim ve Teknoloji Ltd. Sti.