BrowserDB 🚀

Lightning-fast, privacy-first database for modern browsers, now in Pure Rust!

BrowserDB is a high-performance, browser-native database designed as a modern alternative to IndexedDB. Built with a LSM-tree hybrid architecture and intelligent HeatMap indexing, it delivers sub-millisecond queries with 95% cache hit rates.

⚡ Quick Start

Get up and running in 2 minutes:

# 1. Clone the repository
git clone https://github.com/browserdb/browserdb.git
cd browserdb/bindings

# 2. Build and run the example
cargo run --release --example basic_usage

🎯 First database operation:

use browserdb::{BrowserDB, HistoryEntry};

fn main() -> Result<(), Box<dyn std::error::Error>> {
    // Open/create database
    let db = BrowserDB::open("my_app.bdb")?;
    
    // Store some data
    db.history().insert(&HistoryEntry {
        timestamp: 1234567890,
        url_hash: 123,
        title: "My First Page".to_string(),
        visit_count: 1
    })?;
    
    // Retrieve data
    let entry = db.history().get(123)?;
    println!("Entry: {:?}", entry);
    
    Ok(())
}

🎯 Why BrowserDB?

Feature	BrowserDB (Rust)	IndexedDB	SQLite
Read Performance	890K+ ops/sec	10K ops/sec	50K ops/sec
Write Performance	700K+ ops/sec	1K ops/sec	10K ops/sec
Memory Efficiency	<50MB	100MB+	80MB+
Cache Hit Rate	95%	70%	85%
Query Latency	<0.1ms	10ms	2ms

🏗️ Architecture Overview

┌─────────────────┐
│   Application   │
└────────┬────────┘
         │
         ▼
┌─────────────────┐    ┌─────────────────┐
│   Pure Rust     │    │   HeatMap       │
│     Engine      │◄──►│    Index        │
└────────┬────────┘    └─────────────────┘
         │
         ▼
┌─────────────────┐
│  LSM-Tree       │
│   Storage       │
└────────┬────────┘
         │
         ▼
┌─────────────────┐
│   .bdb Files    │
│   (Persistent)  │
└─────────────────┘

Core Components

• 🔥 HeatMap Indexing: Intelligent caching with 95% hit rates
• ⚡ LSM-Tree Storage: Optimized BTreeMap-based MemTable and SSTables
• 🗂️ .bdb Format: Universal browser database format
• 🔄 Mode Operations: Persistent vs Ultra (in-memory) modes
• 🛡️ Data Integrity: CRC32 validation and corruption recovery

🚀 Key Features

Performance

• 890K+ reads/second - Sub-millisecond query response
• 700K+ writes/second - High-throughput data ingestion
• 95% cache hit rate - Intelligent HeatMap optimization
• <50MB memory footprint - Efficient resource usage

Reliability

• Atomic operations - ACID compliance for data integrity
• Corruption recovery - Automatic detection and repair
• Multi-mode support - Persistent and Ultra (RAM) modes
• Zero Dependencies - Pure Rust implementation

🧩 Modular SQL Subsystem

BrowserDB now features a Modular SQL Engine. Adhering to the Unix Philosophy ("Do one thing and do it well"), the core remains a lightning-fast KV store, while SQL is an optional layer on top.

use browserdb::BrowserDB;

// 1. Open the raw, fast core
let db = BrowserDB::open("my.db")?;

// 2. Enable SQL Layer
let sql = std::sync::Arc::new(db).sql();

// 3. Execute SQL
sql.execute("CREATE TABLE users (id INT PRIMARY_KEY, name TEXT)")?;
sql.execute("INSERT INTO users VALUES (1, 'Alice')")?;
let result = sql.execute("SELECT * FROM users WHERE id = 1")?;

This architecture allows you to mix Raw Performance (700k+ ops/sec) with Structured Queries in the same application.

🏃‍♂️ Performance Benchmarks

# Run performance stress test
cd bindings
cargo run --release --example stress_test

# Recent Results (Typical on modern hardware):
# Write Throughput:     714,529 ops/sec
# Read Throughput:      896,192 ops/sec
# Persistence:          Verified

📁 Project Structure

browserdb/
├── 📄 README.md              # This file
├── 📁 bindings/              # 🦀 Main Rust Crate
│   ├── src/                 
│   │   ├── core/            # Core Database Logic
│   │   │   ├── lsm_tree.rs  # Storage engine
│   │   │   ├── format.rs    # File format
│   │   │   ├── heatmap.rs   # Indexing & Bloom Filters
│   │   │   └── modes.rs     # Mode management
│   │   └── lib.rs           # Public API
│   ├── examples/            # 💡 Usage examples
│   └── Cargo.toml           # Rust configuration
├── 📁 scripts/               # 🛠️ Utility scripts
└── 📁 docs/                  # 📚 Documentation

🎯 Use Cases

Browser Applications

• History Management: Fast search through browsing history
• Bookmark Storage: Efficient CRUD operations for bookmarks
• Session Recovery: Quick session restoration
• Resource Caching: High-performance cache layer

Web Applications

• Offline Support: Robust local data persistence
• Real-time Apps: High-throughput event storage
• Analytics: Efficient data collection and querying
• Content Management: Fast content indexing and retrieval

🛠️ Development

Prerequisites

• Rust 1.75+

Contributing

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Add tests
5. Submit a pull request

📊 Database File Types

File	Purpose	Typical Size	Access Pattern
history.bdb	Browsing trails	10-50MB	High read/search
cookies.bdb	Session data	5-20MB	Frequent read/write
cache.bdb	Resource cache	100-500MB	Burst reads
localstore.bdb	Per-origin KV	1-10MB	Write-heavy
settings.bdb	Configuration	<1MB	Rare writes

🔒 Security & Privacy

• Local-first: All data stays on the user's device
• No tracking: Zero telemetry or analytics collection
• Privacy by design: Minimal data exposure
• Open source: Auditable codebase

📄 License

BSD-3-Clause - Open standard for universal browser adoption

🤝 Community

• Issues: GitHub Issues
• Discussions: GitHub Discussions
• Contributing: See Contribution.md

---

🚀 Get Started Now | 📚 Read Docs

Built with ❤️ for the modern web