jgarzik / gdbm-native-rs

Rust crate library for reading/writing GDBM key/value databases

gdbm-native

Rust crate library for reading/writing GDBM key/value databases

Goals

• Read and Write GDBM databases
• Written in safe, native Rust (no FFI).
• Better-than-C: Support all 32-/64-bit and big/little endian variants without recompiling.
• Tuned for modern machines with solid state storage

Status

Alpha: Read-only access works well. Do not use in production.

Major categories of tasks leading to 1.0.0. View the list of issues and milestones for more.

• Open/Close
• Fetch: Get record data by key
• Iterate: First-key/Next-key operations
• Iterate v2: Rust Iterator
• Count: Iterate db and count all records
• Exists: Quick key-exists test
• Insert: Store record
• Remove: Delete record
• Reorganize: Not a priority
• Sync: Write dirty buffers, and fsync(2)
• Import: GDBM ASCII and binary dump formats
• Export: GDBM ASCII and binary dump formats
• Numsync: New, 3rd generation GDBM file format
• Tests: Healthy test coverage
• Code Cleanup: Review by rust experts

Documentation

The best documentation is the original GDBM source code from the GNU project: https://www.gnu.org.ua/software/gdbm/

A sister project also provides additional technical documentation, including file format information.

gdbm-native-rs's Issues

API: Import/Export ASCII dump format

API: Delete

API: Store

API: Rust iterator

A native iterator. Here is sled's example:

// Iterates over key-value pairs, starting at the given key.
let scan_key: &[u8] = b"a non-present key before yo!";
let mut iter = db.range(scan_key..);
assert_eq!(&iter.next().unwrap().unwrap().0, b"yo!");
assert_eq!(iter.next(), None);

Multi-endian support

The matrix of data structure support should take into account

• Support for 32-bit or 64-bit off_t
• Support for runtime switching between big endian and little endian

Extended file header support (v2 aka "numsync")

The GDBM file format was upgraded to a 2nd version, called "numsync" in the documentation.

This includes an extended database header struct, among other details.

Initial read-only tests

Initial set of read-only tests based on pre-generated databases + pre-generated test results (ideally generated by libgdbm and a C program).

API: Import/Binary binary dump format

Not a priority. The ASCII dump format (#9) is preferred and has priority.

Not assigning to a dev or milestone, but a volunteer is welcome to take the task.

Documentation

Hook up rustdoc etc.

API: Sync

Clean up API

Clean up based on Rust standards, by people who know Rust far better than I

API: Compare-and-swap

It is feasible to support a compare-and-swap API, a la sled's:

// Atomic compare-and-swap.
db.compare_and_swap(
    b"yo!",      // key
    Some(b"v1"), // old value, None for not present
    Some(b"v2"), // new value, None for delete
)
.unwrap();