rustlite 0.2.1

A lightweight, high-performance embedded database written in Rust with ACID guarantees
Documentation

RustLite

Crates.io Documentation License: Apache-2.0 Build Status

Changelog

RustLite is a lightweight, high-performance embedded database written entirely in Rust. Designed for applications that need a fast, reliable, and embeddable storage solution with ACID guarantees.

🎯 Vision

RustLite aims to be the go-to embedded database for Rust applications, combining:

  • Performance: Zero-copy operations, memory-mapped I/O, and efficient data structures
  • Reliability: Full ACID compliance with write-ahead logging and crash recovery
  • Simplicity: Single-file deployment, zero configuration, intuitive API
  • Safety: Memory-safe by design using Rust's type system and ownership model

✨ Features

Current (v0.2.0)

  • ✅ Persistent storage with LSM-tree architecture
  • ✅ Write-Ahead Logging (WAL) for crash recovery
  • ✅ SSTable compaction for optimized disk usage
  • ✅ Snapshot backups for point-in-time recovery
  • ✅ Thread-safe concurrent access
  • ✅ Simple, ergonomic API

Roadmap

  • 🔄 v0.3: B-Tree and Hash indexing
  • 🔄 v0.4: SQL-like query engine
  • 🔄 v0.5: Full transaction support with MVCC
  • 🔄 v1.0: Production-ready with ACID guarantees

See docs/ROADMAP.md for detailed plans.

🚀 Quick Start

Add RustLite to your Cargo.toml:

[dependencies]

rustlite = "0.2.0"

Persistent Database (Recommended)

use rustlite::Database;

fn main() -> Result<(), Box<dyn std::error::Error>> {
    // Open a persistent database (creates directory if needed)
    let db = Database::open("./my_database")?;
    
    // Insert data - automatically persisted to disk
    db.put(b"user:1:name", b"Alice")?;
    db.put(b"user:1:email", b"alice@example.com")?;
    
    // Retrieve data
    if let Some(name) = db.get(b"user:1:name")? {
        println!("Name: {}", String::from_utf8_lossy(&name));
    }
    
    // Delete data
    db.delete(b"user:1:email")?;
    
    // Force sync to disk (optional - data is already durable via WAL)
    db.sync()?;
    
    Ok(())
}

Data Persists Across Restarts

use rustlite::Database;

// First run - write data
let db = Database::open("./my_database")?;
db.put(b"counter", b"42")?;
drop(db);

// Later - data is still there!
let db = Database::open("./my_database")?;
assert_eq!(db.get(b"counter")?, Some(b"42".to_vec()));

In-Memory Database (For Testing)

use rustlite::Database;

// Fast in-memory storage (data lost when program exits)
let db = Database::in_memory()?;
db.put(b"temp", b"data")?;

📦 Installation

From crates.io

cargo add rustlite

From source

git clone https://github.com/VIRTUMEM-AI-LABS/rustlite.git

cd rustlite

cargo build --release

🏗️ Architecture

RustLite is built with a modular LSM-tree architecture:

┌──────────────────────────────────────────────────────────┐
│                      Database API                        │
│                   (rustlite crate)                       │
├──────────────────────────────────────────────────────────┤
│  ┌─────────────┐  ┌─────────────┐  ┌─────────────────┐   │
│  │   Memtable  │  │     WAL     │  │    Snapshot     │   │
│  │  (BTreeMap) │  │ (Write Log) │  │   (Backups)     │   │
│  └─────────────┘  └─────────────┘  └─────────────────┘   │
│  ┌─────────────────────────────────────────────────────┐ │
│  │              SSTable Storage                        │ │
│  │    (Sorted String Tables + Compaction)              │ │
│  └─────────────────────────────────────────────────────┘ │
└──────────────────────────────────────────────────────────┘
  • Memtable: In-memory sorted buffer for fast writes
  • WAL: Write-ahead log for crash recovery
  • SSTable: Immutable on-disk sorted files
  • Compaction: Background merging to reclaim space
  • Snapshot: Point-in-time backups

See docs/ARCHITECTURE.md for technical details and docs/README.md for the full documentation index.

🤝 Contributing

We welcome contributions! Please see our CONTRIBUTING.md for guidelines.

Key areas where we need help:

  • Core storage engine implementation
  • Query optimizer
  • Performance benchmarking
  • Documentation and examples
  • Platform-specific optimizations

📋 Requirements

  • Rust 1.70.0 or later
  • Supported platforms: Linux, macOS, Windows

🧪 Testing

# Run tests

cargo test


# Run with logging

RUST_LOG=debug cargo test


# Run benchmarks

cargo bench

📊 Benchmarks

Performance benchmarks will be published as the project matures. Early benchmarks show:

  • Sequential writes: TBD
  • Random reads: TBD
  • Concurrent operations: TBD

🔒 Security

RustLite takes security seriously. Please report any security vulnerabilities to security@rustlite.dev.

📜 License

This project is licensed under the Apache License, Version 2.0 (LICENSE or http://www.apache.org/licenses/LICENSE-2.0).

Contribution

Unless you explicitly state otherwise, any contribution intentionally submitted for inclusion in RustLite by you shall be under the terms and conditions of the Apache License, Version 2.0, without any additional terms or conditions.

🌟 Acknowledgments

RustLite is inspired by excellent databases like SQLite, LevelDB, and RocksDB.

📞 Contact & Community

🗺️ Status

Current Status: Early development (v0.1.0)

RustLite is in active development and not yet ready for production use. We're working hard to deliver a stable v1.0 release. Star the repo to follow our progress!

Made with ❤️ by the RustLite community