gnudbm

See the documentation for details.

This project provides ergonomic and idiomatic Rust bindings to gdbm, a lightweight local key/value database. It allows easy storage and retrieval of any type that implements Serialize and Deserialize.

Requirements

By default, this package includes a recent gdbm and builds it as a static lib. If you would like to link against the system gdbm, ensure it is up to date (1.14+) and build with the system-gdbm feature.

Usage

First, add the following to your Cargo.toml:

[dependencies]
gnudbm = "0.2.3"

And to your crate root:

extern crate gnudbm;

lib.rs:

Gnudbm is an ergonomic, idiomatic wrapper for gdbm.

With built in support for Serde and bincode, It provides fast and easy local key/value storage of any type implementing Serialize.

For an overview of available database operations, see the documentation for RwHandle.

Examples

Opening or creating a database file with a GdbmOpener:

let db_path = PathBuf::from("path/to/my.db");
let mut db = GdbmOpener::new()
    .create(true)
    // there are two types of database handle;
    // the other is instantiated with `GdbmOpener::readonly`
    .readwrite(&db_path)
    .expect("db creation failed");

When fetching and storing, your key can be any type that implements AsRef<[u8]>; for instance one of String/&str. Values are any type that implements Serialize and Deserialize.

// 'db' is a previously configured database
db.store("my key", "an important value").unwrap();

// fetch returns an Entry, which wraps a pointer to the raw data
let entry = db.fetch("my key").unwrap();
assert_eq!(entry.as_bytes(), "my key".as_bytes());

// the data can be deserialized, borrowing if possible.
// The result is bound to the lifetime of the Entry.
let as_str: &str = entry.deserialize().unwrap();
assert_eq!(as_str, "my key");

Use a custom type with Serde:

use serde::{Serialize, Deserialize};

#[derive(Serialize, Deserialize)]
struct MyStruct<'a> {
    name: &'a str,
    counts: Vec<u64>,
}

let name: String = "Colin".into();
let value = MyStruct {
    name: &name,
    counts: vec![4, 2, 0],
};

// 'db' is a previously configured database
db.store("my key", &value).unwrap();

let entry = db.fetch("my key").unwrap();
let fetched: MyStruct = entry.deserialize().unwrap();

assert_eq!(value.name, fetched.name);