Crate ngdb 

NGDB - High-Performance RocksDB Wrapper

NGDB provides a clean, idiomatic Rust interface to RocksDB with zero async overhead and built-in thread-safety.

Features

• Synchronous API: All operations are fast and synchronous - no async overhead
• Type-safe: Generic over key/value types with trait-based serialization
• Zero RocksDB exposure: Users never deal with RocksDB types directly
• Thread-safe: Built on Arc with multi-threaded column family support
• Column Families: Store multiple types in one database using collections
• Efficient: Multi-get operations, batching, transactions, and snapshots
• Replication: Built-in support for multi-node replication with conflict resolution

Quick Start

use ngdb::{DatabaseConfig, Storable, ngdb};

#[ngdb("users")]
struct User {
    id: u64,
    name: String,
    email: String,
}

impl Storable for User {
    type Key = u64;
    fn key(&self) -> Self::Key {
        self.id
    }
}

fn main() -> Result<(), ngdb::Error> {
    let db = DatabaseConfig::new("./data")
        .create_if_missing(true)
        .add_column_family("users")
        .open()?;

    let user = User {
        id: 1,
        name: "Alice".to_string(),
        email: "alice@example.com".to_string(),
    };
    user.save(&db)?;

    let users = User::collection(&db)?;
    let retrieved: Option<User> = users.get(&1)?;
    println!("Retrieved: {:?}", retrieved);

    Ok(())
}

Batch Operations

let users = db.collection::<User>("users")?;

let mut batch = users.batch();
for i in 0..1000 {
    batch.put(&User { id: i, name: format!("User {}", i) })?;
}
batch.commit()?;

Transactions

let txn = db.transaction()?;
let accounts = txn.collection::<Account>("accounts")?;

accounts.put(&Account { id: 1, balance: 100 })?;
accounts.put(&Account { id: 2, balance: 200 })?;

txn.commit()?;

Replication

NGDB provides production-ready replication support for multi-node deployments:

// Setup replica node
let db = DatabaseConfig::new("./data/replica")
    .create_if_missing(true)
    .add_column_family("users")
    .open()?;

// Configure replication
let config = ReplicationConfig::new("replica-1")
    .enable()
    .with_peers(vec!["primary-1".to_string()]);

let manager = ReplicationManager::new(db, config)?;

// Apply replication logs from primary (received via network)
let log = ReplicationLog::new(
    "primary-1".to_string(),
    ReplicationOperation::Put {
        collection: "users".to_string(),
        key: vec![1, 2, 3],
        value: vec![4, 5, 6],
    },
).with_checksum();

manager.apply_replication(log)?;

Features:

• Idempotent: Safe to apply the same operation multiple times
• Conflict Resolution: LastWriteWins, FirstWriteWins, or Custom strategies
• Checksums: Optional data integrity verification
• Hooks: Extensible hook system for custom replication logic
• Batching: Efficient batch operation replication

See the replication module and examples for more details.

Re-exports

pub use replication::BatchOp;

pub use replication::ConflictResolution;

pub use replication::ReplicationConfig;

pub use replication::ReplicationHook;

pub use replication::ReplicationLog;

pub use replication::ReplicationManager;

pub use replication::ReplicationOperation;

pub use replication::ReplicationStats;

Modules

prelude

Re-export commonly used types

replication

Replication support for NGDB

Macros

db_error

replication_error

serialization_error

Structs

BackupInfo

Information about a database backup

Batch

A batch of write operations

BincodeCodec

Borsh-based codec implementation (default)

Collection

A typed collection for storing and retrieving values

Database

The main database handle

DatabaseConfig

Configuration builder for opening a database

Iterator

Iterator over collection items

OpenOptions

Additional options for advanced database configuration

Ref

A reference to another Storable object.

Snapshot

A consistent snapshot of the database

Transaction

A database transaction for atomic operations

TransactionCollection

A typed collection view within a transaction

Enums

Error

Main error type for all NGDB operations

IterationStatus

Result of an iteration operation

Traits

Codec

Trait for encoding and decoding values to/from bytes.

HasCollectionName

Trait for providing collection name for a type.

KeyType

Trait for types that can be used as database keys.

Referable

Trait for types that can be referenced by Ref<T> and contain references themselves.

Storable

The core trait that types must implement to be stored in NGDB.

Type Aliases

Result

Result type alias for NGDB operations

Attribute Macros

ngdb

Attribute macro for defining an NGDB collection