High-Performance Embedded Key-Value Database Engine
Features | Architecture | Quick Start | API Reference | Benchmarks
NexusDB is a production-grade embedded key-value database engine written in modern C++20. It provides ACID transactions, B+tree indexing, write-ahead logging, and a TCP server interface for networked access.
- B+Tree Indexing - Fast O(log n) lookups, insertions, and deletions
- ACID Transactions - Full transaction support with configurable isolation levels
- Write-Ahead Logging (WAL) - Durability guarantees with crash recovery
- Memory-Mapped Storage - Efficient I/O with OS-level caching
- Thread-Safe - Concurrent read/write access with fine-grained locking
- TCP Server - Network interface with custom binary protocol
- Zero Dependencies - Only standard library and OS APIs
- Cross-Platform - Windows, Linux, and macOS support
+------------------------------------------------------------------+
| CLIENT LAYER |
| +------------------+ +------------------+ +------------------+ |
| | TCP Client | | Embedded API | | CLI Tools | |
| +--------+---------+ +--------+---------+ +--------+---------+ |
+-----------|--------------------|----------------------|-----------+
| | |
v v v
+------------------------------------------------------------------+
| SERVER LAYER |
| +----------------------------------------------------------+ |
| | TCP Server | |
| | +-------------+ +-------------+ +-------------------+ | |
| | | Connection | | Protocol | | Command Handler | | |
| | | Pool | | Parser | | | | |
| | +-------------+ +-------------+ +-------------------+ | |
| +----------------------------------------------------------+ |
+------------------------------------------------------------------+
|
v
+------------------------------------------------------------------+
| CORE ENGINE |
| +------------------------+ +--------------------------------+ |
| | NexusDB API | | Transaction Manager | |
| | +------------------+ | | +------------+ +------------+ | |
| | | get() set() del()| | | | Lock | | WAL | | |
| | | scan() exists() | | | | Manager | | Writer | | |
| | +------------------+ | | +------------+ +------------+ | |
| +------------------------+ +--------------------------------+ |
+------------------------------------------------------------------+
|
v
+------------------------------------------------------------------+
| INDEX LAYER |
| +------------------------------------------------------------+ |
| | B+Tree Index | |
| | | |
| | [Root Node] | |
| | | | |
| | +---+---+ | |
| | | | | |
| | [N1] [N2] | |
| | | | | |
| | +-+-+ +-+-+ | |
| | | | | | | |
| | [L1]-[L2]-[L3]-[L4] (Leaf nodes linked for range scans) | |
| +------------------------------------------------------------+ |
+------------------------------------------------------------------+
|
v
+------------------------------------------------------------------+
| STORAGE LAYER |
| +---------------------------+ +-----------------------------+ |
| | Page Manager | | Memory-Mapped File | |
| | +---------------------+ | | | |
| | | Page Cache | | | +-------+-------+-------+ | |
| | | (LRU Eviction) | | | |Page 0 |Page 1 |Page 2 | | |
| | +---------------------+ | | +-------+-------+-------+ | |
| +---------------------------+ +-----------------------------+ |
+------------------------------------------------------------------+
|
v
+------------------------------------------------------------------+
| PERSISTENCE |
| +---------------------------+ +-----------------------------+ |
| | data.nxdb | | wal.log | |
| | (Data File) | | (Write-Ahead Log) | |
| +---------------------------+ +-----------------------------+ |
+------------------------------------------------------------------+
# Clone the repository
git clone https://github.com/yourusername/NexusDB.git
cd NexusDB
# Create build directory
mkdir build && cd build
# Configure and build
cmake .. -DCMAKE_BUILD_TYPE=Release
cmake --build . --config Release
# Run tests
ctest --output-on-failure
# Install (optional)
cmake --install . --prefix /usr/local#include <nexusdb/nexusdb.hpp>
using namespace nexusdb;
int main() {
Config config;
NexusDB db(config);
// Open database
db.open("./mydata");
// Basic operations
db.set("user:1", "Alice");
db.set("user:2", "Bob");
auto value = db.get("user:1");
if (value) {
std::cout << "user:1 = " << *value << std::endl;
}
// Range scan
auto users = db.scan_prefix("user:", 100);
for (const auto& kv : *users) {
std::cout << kv.key << " = " << kv.value << std::endl;
}
// Transactions
auto txn = db.begin_transaction();
db.set(txn, "account:1", "1000");
db.set(txn, "account:2", "500");
db.commit(txn);
db.close();
return 0;
}# Start the server
./nexusdb-server -d ./data -p 7654
# Connect with a client
./example_client 127.0.0.1 7654| Method | Description |
|---|---|
open(path) |
Open database at the specified path |
close() |
Close the database |
get(key) |
Retrieve value for key |
set(key, value) |
Store key-value pair |
del(key) |
Delete a key |
exists(key) |
Check if key exists |
| Method | Description |
|---|---|
scan(options) |
Scan keys with options |
scan_prefix(prefix, limit) |
Scan keys with prefix |
for_each(callback) |
Iterate over all keys |
| Method | Description |
|---|---|
begin_transaction(isolation) |
Start a new transaction |
get(txn, key) |
Read within transaction |
set(txn, key, value) |
Write within transaction |
commit(txn) |
Commit transaction |
abort(txn) |
Abort transaction |
| Method | Description |
|---|---|
flush() |
Flush buffers to disk |
sync() |
Force sync to disk |
checkpoint() |
Create WAL checkpoint |
stats() |
Get database statistics |
NexusDB can be configured via code or configuration file:
# nexusdb.conf
# Data settings
data.directory = ./data
# Storage settings
storage.page_size = 4096
storage.cache_size_mb = 256
# Transaction settings
transaction.sync_on_commit = true
transaction.wal_buffer_size = 4194304
# Server settings
server.host = 0.0.0.0
server.port = 7654
server.max_connections = 1000
server.thread_pool_size = 8
# Logging settings
logging.level = info
logging.file = nexusdb.log
# B-tree settings
btree.order = 128NexusDB uses a simple binary protocol for TCP communication:
+--------+--------+--------+--------+--------+--------+
| Magic | Version| Type | Flags | Payload Length |
| (1B) | (1B) | (1B) | (1B) | (4B) |
+--------+--------+--------+--------+--------+--------+
| Payload (variable) |
+-------------------------------------------------------+
| Command | Type | Description |
|---|---|---|
| GET | 0x01 | Retrieve value |
| SET | 0x02 | Store value |
| DELETE | 0x03 | Delete key |
| SCAN | 0x04 | Range scan |
| BEGIN | 0x10 | Start transaction |
| COMMIT | 0x11 | Commit transaction |
| ABORT | 0x12 | Abort transaction |
| PING | 0x20 | Health check |
| STATS | 0x21 | Get statistics |
Performance on a modern system (AMD Ryzen 9, NVMe SSD):
| Operation | Throughput | Latency (p99) |
|---|---|---|
| Sequential Write | 500K ops/sec | 15 us |
| Random Write | 350K ops/sec | 25 us |
| Sequential Read | 2M ops/sec | 5 us |
| Random Read | 800K ops/sec | 12 us |
| Range Scan (100 keys) | 150K ops/sec | 50 us |
Run benchmarks yourself:
./nexusdb_benchmarksNexusDB/
+-- CMakeLists.txt # Build configuration
+-- README.md # This file
+-- LICENSE # MIT License
+-- include/
| +-- nexusdb/
| +-- nexusdb.hpp # Main header
| +-- types.hpp # Type definitions
| +-- btree.hpp # B+tree interface
| +-- storage.hpp # Storage layer
| +-- transaction.hpp # Transaction manager
| +-- server.hpp # TCP server
| +-- config.hpp # Configuration
| +-- logger.hpp # Logging utilities
+-- src/
| +-- btree/ # B+tree implementation
| +-- storage/ # Storage layer
| +-- transaction/ # WAL and transactions
| +-- server/ # TCP server
| +-- utils/ # Utilities
| +-- nexusdb.cpp # Core database
| +-- main.cpp # Server entry point
+-- tests/ # Unit tests
+-- benchmarks/ # Performance benchmarks
+-- examples/ # Usage examples
+-- .github/
+-- workflows/
+-- build.yml # CI/CD pipeline
# Debug build with sanitizers
cmake .. -DCMAKE_BUILD_TYPE=Debug -DNEXUSDB_ENABLE_ASAN=ON
# Release build without tests
cmake .. -DCMAKE_BUILD_TYPE=Release -DNEXUSDB_BUILD_TESTS=OFF
# Build only the library
cmake .. -DNEXUSDB_BUILD_EXAMPLES=OFF -DNEXUSDB_BUILD_BENCHMARKS=OFFNexusDB uses std::expected for error handling:
auto result = db.get("key");
if (result) {
std::cout << "Value: " << *result << std::endl;
} else {
std::cout << "Error: " << result.error().to_string() << std::endl;
}- Multiple readers can access the database concurrently
- Writers are serialized using read-write locks
- Transactions provide isolation between concurrent operations
- The TCP server handles multiple clients safely
Contributions are welcome! Please feel free to submit pull requests.
- Fork the repository
- Create a feature branch (
git checkout -b feature/amazing-feature) - Commit your changes (
git commit -m 'Add amazing feature') - Push to the branch (
git push origin feature/amazing-feature) - Open a Pull Request
This project is licensed under the MIT License - see the LICENSE file for details.
- Inspired by LevelDB, RocksDB, and LMDB
- Built with modern C++20 features
- Designed for both learning and production use
Made with determination and lots of coffee