snaildb

An embedded, persistent key-value store written in Rust.

Principles

• High write throughput - Optimized for write-heavy workloads
• Durability - Write-ahead logging (WAL) ensures data persistence

Installation

Add to your Cargo.toml:

[dependencies]
snaildb = "0.2"

Or install the binaries from GitHub Releases.

Usage

Library Usage (snaildb)

Basic Operations

use snaildb::SnailDb;
use anyhow::Result;

fn main() -> Result<()> {
    // Open or create a database at a directory
    let mut db = SnailDb::open("./data")?;
    
    // Store a key-value pair
    db.put("user:1", b"Alice")?;
    db.put("user:2", b"Bob")?;
    
    // Retrieve a value
    match db.get("user:1")? {
        Some(value) => println!("Found: {:?}", String::from_utf8_lossy(&value)),
        None => println!("Key not found"),
    }
    
    // Delete a key
    db.delete("user:2")?;
    
    Ok(())
}

Custom Flush Threshold

use snaildb::SnailDb;

let mut db = SnailDb::open("./data")?
    .with_flush_threshold(256 * 1024 * 1024); // Flush memtable after 256 MiB

Working with Strings

let mut db = SnailDb::open("./data")?;

// Store string values
db.put("name", "snaildb")?;

// Retrieve as string
if let Some(bytes) = db.get("name")? {
    let value = String::from_utf8_lossy(&bytes);
    println!("Name: {}", value);
}

Error Handling

use snaildb::SnailDb;
use anyhow::{Result, Context};

fn store_data() -> Result<()> {
    let mut db = SnailDb::open("./data")
        .context("Failed to open database")?;
    
    db.put("key", "value")
        .context("Failed to store key-value pair")?;
    
    Ok(())
}

Examples

See the examples directory for more detailed usage examples. Run them with:

cargo run --example <example_name> --package snaildb

Configuration

Flush Threshold

The flush threshold determines when the in-memory memtable is flushed to disk as an SSTable. Default is 64 MiB.

let mut db = SnailDb::open("./data")?
    .with_flush_threshold(256 * 1024 * 1024); // Custom threshold

Architecture

snailDB uses an LSM-tree (Log-Structured Merge-tree) architecture:

1. Memtable - In-memory structure for recent writes
2. WAL (Write-Ahead Log) - Ensures durability by logging all writes
3. SSTables - Immutable on-disk structures created from flushed memtables

Roadmap

Current work in progress:

• Durable async WAL - Group commit and crash recovery improvements
• Compaction - Background compaction to manage SSTable growth
• Iterators & scans - Efficient range queries and prefix scans
• Performance optimizations - Block caching and metrics

License

Licensed under the Apache License, Version 2.0. See LICENSE file for details.

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

Links

• GitHub Repository
• Crates.io
• Documentation