# MagnumDB
> Modern Open Source Embedded Database Engine in Native Rust
[](https://github.com/sohamdev77/MagnumDB/actions)
[](https://opensource.org/licenses/MIT)
[](https://www.rust-lang.org/)
[](https://crates.io/crates/magnumdb)
[](https://docs.rs/magnumdb)
[](https://github.com/sohamdev77/MagnumDB/stargazers)
[](https://github.com/sohamdev77/MagnumDB/issues)
MagnumDB is an open-source embedded key-value and SQL database engine written 100% from scratch in native Rust. Designed for performance, reliability, and modularity.
## Features
- **Embedded Engine**: Runs directly inside Rust binaries with zero external C/C++ dependencies.
- **WAL Durability**: Write-Ahead Logging (WAL) with TxID framing and CRC32 checksums ensures crash recovery.
- **B+ Tree Indexing**: Custom 4KB page disk pager, LRU buffer pool management, overflow pages, and leaf page recycling.
- **Relational SQL Query Engine**: Hash JOINs (`INNER JOIN`, `LEFT JOIN`), `GROUP BY` & `HAVING` aggregations, `ORDER BY` sorting, `LIMIT` & `OFFSET` pagination, and composite indexes.
- **MVCC & Transactions**: Thread-safe MVCC row headers (`xmin`, `xmax`) and transaction logging with `BEGIN`, `COMMIT`, and `ROLLBACK`.
- **Authentication & RBAC**: PostgreSQL-compatible MD5 authentication and `CREATE USER` role-based access control.
- **PostgreSQL Protocol & Extended Querying**: Native PostgreSQL Wire Protocol (`pgwire`) supporting prepared statements and `$1`, `$2` parameter binding (`Parse`, `Bind`, `Execute`).
- **Multi-Client TCP Server**: Async TCP server powered by Tokio with connection limits and idle timeouts.
---
## What's New in v0.4.2
Version `0.4.2` introduces Authentication, Role-Based Access Control (RBAC), and thread-safe MVCC concurrency:
- 🔒 **Authentication Handshake**: PostgreSQL-compatible MD5 password authentication over `pgwire`.
- 👤 **`CREATE USER` DDL**: Provision users and manage roles directly via SQL:
```sql
CREATE USER admin WITH PASSWORD 'secure_pass';
```
- 🧵 **Thread-Safe MVCC**: Safe, concurrent transaction execution using `parking_lot::RwLock` for multi-client scale.
- ↕️ **`ORDER BY`, `LIMIT`, `OFFSET`**: Sort and paginate query results.
---
## Architecture
```mermaid
graph TD
A[Client / magnum shell / psql] -->|SQL Query| B(SQL Parser)
B -->|AST| C(Query Executor)
C -->|Reads/Writes| D[B+ Tree Index]
C -->|Logs| E[(WAL - Write Ahead Log)]
D -->|Request Page| F(Buffer Pool Manager)
F -->|Evict/Load 4KB Pages| G[(Disk / Pager)]
style A fill:#f9f,stroke:#333,stroke-width:2px
style D fill:#bbf,stroke:#333,stroke-width:2px
style F fill:#bbf,stroke:#333,stroke-width:2px
style G fill:#dfd,stroke:#333,stroke-width:2px
style E fill:#dfd,stroke:#333,stroke-width:2px
```
---
## Installation
Add MagnumDB to your `Cargo.toml`:
```toml
[dependencies]
magnumdb = "0.4.2"
```
---
## Quick Start (Embedded Key-Value)
```rust
use magnumdb::{Database, Config};
fn main() -> anyhow::Result<()> {
let config = Config::default().with_path("./my_database");
let mut db = Database::open(config)?;
// Embedded Key-Value API
db.put(b"user:100", b"Soham")?;
let val = db.get(b"user:100")?;
if let Some(bytes) = val {
println!("Found: {}", String::from_utf8_lossy(&bytes));
}
db.close()?;
Ok(())
}
```
---
## Embedded SQL Usage
```rust
use magnumdb::{Database, Config};
use magnumdb::sql::{Executor, Parser};
fn main() -> anyhow::Result<()> {
let config = Config::default().with_path("./sql_data");
let mut db = Database::open(config)?;
let mut exec = Executor::new(&mut db);
exec.execute(Parser::parse("CREATE TABLE users(id INT, name TEXT)")?)?;
exec.execute(Parser::parse("INSERT INTO users VALUES(1, 'Alice')")?)?;
let res = exec.execute(Parser::parse("SELECT * FROM users ORDER BY id DESC LIMIT 5")?)?;
println!("{}", res);
Ok(())
}
```
---
## Contributing & License
We welcome contributions! Please review [CONTRIBUTING.md](CONTRIBUTING.md).
Licensed under the [MIT License](LICENSE).