OsmiumDB

A dense, chunk-oriented storage engine with explicit hot/cold memory control.

What is OsmiumDB?

OsmiumDB (OSDB) is an embedded key-value storage engine designed for workloads that need:

• Zero-copy reads — Borrow directly from chunk buffers, no allocations on the hot path
• Explicit memory control — Chunks are either awake (in memory) or sleeping (on disk)
• Columnar support — Fixed-width numeric columns for efficient scans and aggregations
• Crash recovery — WAL-based durability with idempotent replay

Quick Start

use osmiumdb::{Engine, EngineConfig};

fn main() -> Result<(), Box<dyn std::error::Error>> {
    let config = EngineConfig::new("./my_db");
    let engine = Engine::open(config)?;

    // Write
    engine.put(b"hello", b"world")?;

    // Read
    if let Some(value) = engine.get(b"hello")? {
        println!("Got: {}", String::from_utf8_lossy(&value));
    }

    // Scan
    for (key, value) in engine.scan(b"a"..b"z")? {
        println!("{:?} = {:?}", key, value);
    }

    Ok(())
}

Features

Installation

Add to your Cargo.toml:

[dependencies]
osmiumdb = "0.1"

For mmap support:

[dependencies]
osmiumdb = { version = "0.1", features = ["mmap"] }

Performance

Benchmarks on 10,000 records (32-byte keys, 256-byte values):

Documentation

• TECHNICAL.md — Architecture, internals, and design decisions
• ENCODE.md — Binary format specification

License

This project is licensed under the Mozilla Public License 2.0.

Author

Created by @YelenaTor27021

OsmiumDB — Dense storage for dense workloads.