GitHub - sohzm/jasonisnthappy: simple, embeddable document database with acid guarantees

A lightweight, embedded document database written in Rust with ACID transactions and MVCC support.

Features

• Pure Rust — no unsafe code in the core library
• Cross-Platform — macOS, Linux, and Windows
• ACID Transactions — full commit/rollback with conflict detection
• MVCC — snapshot isolation; reads never block writes
• Document Storage — JSON documents with automatic ID generation and upsert
• B-tree Storage Engine — copy-on-write with single-field, compound, and unique indexes
• Write-Ahead Logging (WAL) — checksummed for crash recovery and durability
• Full-text Search — TF-IDF scoring with Unicode tokenization
• Query Language — logical, comparison, and membership operators with dot notation
• Aggregation Pipeline — group, match, sort, project, and accumulator stages
• Schema Validation — JSON Schema enforcement on documents
• Change Streams — real-time notifications on insert, update, and delete
• Bulk Operations — high-throughput batch inserts and writes
• QueryBuilder — fluent API with sorting, pagination, and projections
• Backup & Restore — point-in-time snapshots with file locking
• Garbage Collection — reclaim space from old MVCC versions
• Read-only Mode — safe concurrent access
• Web UI & REST API — built-in dashboard and CRUD endpoints
• CLI — interactive REPL and command-line access
• Metrics — track transactions, cache, WAL, and errors
• Configurable — tunable cache, checkpoints, permissions, and limits
• LRU Page Cache — in-memory caching with corruption detection
• Language Bindings — Go, Python, and JavaScript (Node/Deno/Bun) via C FFI

Quick Start

use jasonisnthappy::core::database::Database;
use serde_json::json;

fn main() -> Result<(), Box<dyn std::error::Error>> {
    let db = Database::open("mydb.db")?;

    let mut tx = db.begin()?;
    let mut users = tx.collection("users");

    let user = json!({"name": "Alice", "age": 30});
    let id = users.insert(user)?;

    tx.commit()?;
    db.close()?;

    Ok(())
}

Performance Benchmarks

All benchmarks run on a single-threaded workload with ACID guarantees and MVCC enabled.

Write Performance (100 documents per transaction)

Measures sustained write throughput with full durability (WAL + fsync)

Read Performance (1500 documents)

Measures concurrent read performance with MVCC snapshot isolation

Bulk Insert Performance (per transaction)

Bulk inserts show significant throughput improvements due to B-tree batching

Query Performance

Query performance remains consistently fast even with larger datasets

Update Performance

Updates include MVCC versioning and WAL logging for full ACID compliance

Key Performance Characteristics

• ACID Compliant: All operations include full transaction support with durability guarantees
• MVCC Overhead: Minimal - reads don't block writes, writes don't block reads
• Bulk Efficiency: ~19,150 documents/sec for bulk inserts (1000 docs/tx)
• Query Speed: Sub-millisecond queries even on 2500+ document collections
• Concurrent Writes: Linear scaling with thread count up to core count
• Single Insert: ~8ms with full fsync durability (WAL + DB file)

Running Tests

# Unit and integration tests
cargo test --lib
cargo test --tests

# Stress tests
cargo test --test stress_tests -- --nocapture

# Regression tests
cargo test --test regression -- --nocapture

# Debug tests
cargo test --test debug -- --nocapture

Running Benchmarks

cargo run --release --example bench_all

Language Bindings

jasonisnthappy can be used from multiple languages:

• Rust: Use the crate directly (this repo)
• Go: bindings/go/
• JavaScript (Node/Deno/Bun): bindings/napi/
• Python: bindings/python/

All bindings use a shared C FFI layer. See bindings/README.md for details.

Building Bindings

# Build for all platforms (requires Docker)
./scripts/build.sh

# Or just macOS for quick testing
./scripts/build-simple.sh

Outputs go to builds/ directory ready for GitHub releases.

See bindings/PUBLISHING.md for publishing guide.

Star History

License

MIT