zaxonlite
I would like to share an Embedded Distributed SQL Database Built on SQLite and Paxos in Zig
GitHub Repository: GitHub - insanai/zaxonlite: SQLite that several machines keep identical. Embedded replicated SQLite on paxos-zig, with the zaxon CLI. · GitHub
zaxonlite is an embeddable, distributed SQL database written in Zig. It combines SQLite with the Multi-Paxos consensus engine from paxos-zig GitHub - insanai/paxos-zig: A bounded, deterministic Paxos and Multi-Paxos library for Zig. No I/O, no threads, no clocks. · GitHub to create a replicated database where write can be done to any node, read from any node, and maintain byte-identical database replicas across machine crashes, network partitions, and restarts. Overall system ships as a native Zig package, a standalone CLI (zaxon), a C ABI library (libzaxonlite.a and include/zaxonlite.h), and a Python SDK (zxlite) with first-class SQLAlchemy support.
During the development learned following things:
- Replicate WAL Pages, Not SQL Text: Most replicated SQL databases send raw SQL queries to every node, this approach did not work when queries contain non-deterministic operations (like random(), datetime(‘now’), or auto-incrementing triggers). zaxonlite executes transactions exactly once on the elected leader, captures the resulting page images from SQLite’s Write-Ahead Log (WAL), and replicates those page frames through Paxos. Replicas apply byte-level page updates directly. This guarantees identical SQLite databases without re-executing SQL queries.
- Consider Journal as the Truth and Database File is a Cache: Every transaction payload is framed, checksummed, appended to a Paxos log, and fsynced to stable storage before consensus commit. The SQLite file (current.db) is treated as materialized state. Even if deleted, it can be rebuilt from the latest snapshot plus the journal suffix.
- Linearizable Quorum Reads Without Disk Syncs: In addition to local reads (any) and leader reads (leader), zaxonlite supports linearizable reads via a Multi-Paxos quorum read fence, ensuring strong consistency without incurring log appends or disk fsync overhead per read.
- Python DB-API and SQLAlchemy Integration (zxlite): The project provides an audited Python driver (zxlite) following the Python DB-API (PEP 249) standard and a dedicated SQLAlchemy 2.0+ dialect (zxlite[sqlalchemy]). It supports local embedded instances (zxlite:////path/to/data) as well as clustered deployments (zxlite:///?seed=host1:9901&seed=host2:9901), supporting SQLAlchemy Core, ORM unit-of-work, schema reflection, and savepoints.
- Integrated Full-Text and Vector Hybrid Search: Statically links SQLite FTS5 for keyword search and pinned sqlite-vec (v0.1.9) for vector search. It features a compact 1-bit
coarse scan reranked by SIMD cosine distance kernels, alongside Reciprocal Rank Fusion (rrf/dbsf) functions registered across every connection. - Transport Security and Decided Membership: Production TCP connections mandate Mutual TLS 1.3 with certificate Common Names bound to consensus-registered node IDs. Cluster membership modifications (such as online voter replacement via zaxon replace-voter) are driven through consensus, permanently retiring replaced node identities.
Benchmarks (vs rqlite)
We benchmarked it across a 3-node cluster on an Apple Silicon machine (macOS arm64, Zig 0.16.0, rqlite v10.2.7), with 3 durable voters per system:
1. Sequential Single-Client Writes (1 client, 256-byte rows, fsync per write)
| System | Writes / sec | p50 Latency | p99 Latency |
|---|---|---|---|
| zaxonlite | 28.0 /s | 35.1 ms | 45.9 ms |
| rqlite v10.2.7 | 44.5 /s | 22.0 ms | 33.7 ms |
Note: rqlite performs faster on single-client sequential fsync writes due to lighter disk bookkeeping overhead per transaction.
2. Concurrent Order-Processing Simulation Under Chaos (4 clients, idempotent writes, linearizable reads, fault schedule)
| Workload Condition / Recovery Metric | zaxonlite | rqlite v10.2.7 |
|---|---|---|
| Healthy throughput | 1,783 /s | 177 /s |
| Throughput (follower crashed) | 1,073 /s | 222 /s |
| Throughput (leader crashed) | 387 /s | 94 /s |
| Leader crash to first successful write | 591 ms | 2,190 ms |
| Follower catch-up time | 112 ms | 949 ms |
| Full 3-node cluster restart time | 446 ms | 1,626 ms |
Under concurrent application workloads and active node failover, zaxonlite achieves significantly higher throughput and faster recovery times due to in-memory consensus pipelining and direct page-level state catch-up.
Supported Zig versions
• Zig 0.16.0-dev (tags: zig-0-16)
AI / LLM usage disclosure
We have used LLM extensively during development, testing and documentation.
Note: This post is written by me not AI, but if this form of content is unacceptable, please let me know and next time won’t post it.