logdb

Embedded, append-only, crash-recoverable, optionally tamper-proof local log database. Built in Rust.

Documentation

Full documentation lives under docs/. See the Usage Guide and the Development Guide.

API reference: run cargo doc --open (also available on docs.rs once published).

Quick Start

use logdb::{Config, LogDb};

let db = LogDb::open(Config::default())?;
let seq = db.append(b"hello")?;
db.flush()?;
let record = db.read(seq)?.unwrap();
assert_eq!(record.content, b"hello");

Features

• Lock-free writes: multi-producer CAS ring buffer, p50 < 100ns
• Durability modes: Sync (fsync per batch), Batch (periodic), Async (caller-driven)
• Hash chain (hash-chain feature): BLAKE3 keyed tamper-evident integrity
• Compression (compression feature): streaming zstd per-frame
• Encryption (encryption feature): AES-256-GCM per-frame
• WAL checkpoint: persistent, survives crash
• Crash recovery: torn-write detection + hash chain verification
• Sharding: multi-ring for high-core scalability
• Remote push (remote-push feature): async durable record push

As a WAL

// Write
db.append_batch(&[redo1, undo, redo2])?;  // atomic
db.flush()?;
db.checkpoint(db.durable_cursor());       // persistent

// Recover after crash
let report = db.recovery_report();
// report: { from_sequence, to_sequence, count }
for rec in db.replay_from(report.from_sequence)? {
    apply(rec?);
}

// Ops monitoring
let (used, _total) = db.wal_usage();   // WAL space in use

Full example: cargo run --example wal

Feature Flags

Shutdown & drop

LogDb spawns background threads (Committer, Sealer). For guaranteed durability, call shutdown(timeout) (consumes the handle, joins threads) or drain(timeout) (shared-safe, flushes without consuming). Drop performs a best-effort bounded drain (≤5 s) of already-published records and emits a tracing warning if it cannot finish — a safety net, not a guarantee. It is skipped during panic unwinding.

Testing

cargo test                          # 140+ unit tests (default features)
cargo test --features compression   # + compression
cargo test --test fuzz              # property-based (proptest)
cargo +nightly fuzz run <target>    # libfuzzer + ASan

Architecture

Many producer threads
     │ append(content)
     ▼
┌─────────────────────────┐
│  Ring (optionally sharded)  │  ← lock-free CAS claim, inline ≤ 256B = zero alloc
│  Slot: { content, hash } │
└──────────┬──────────────┘
           │
    (optional) Sealer thread  ← BLAKE3 keyed hash chain
           │
    Committer thread          ← batch serialize + pwrite + fdatasync
           │
    ┌──────┴──────┐
    │ Segment file │         ← append-only, rolls when full, checkpoint-truncated
    └─────────────┘
           │
    Reader / Pusher         ← point/range reads / remote push

Performance baseline (SATA SSD, 8-vCPU cloud VM)

License

Apache-2.0. Third-party attributions: THIRDPARTY.md.

Security

Using the encryption or hash-chain features? Read the threat model and key management first. To report a vulnerability, see ../SECURITY.md.