vsdb

vsdb is a high-performance, embedded database with an API similar to Rust's standard collections.

This crate provides high-level, typed data structures that are backed by a persistent key-value store. It is the primary crate for end-users.

This is a simplified version of the original vsdb, retaining only the most practical and stable parts.

Installation

Add this to your Cargo.toml:

[dependencies]
vsdb = "7.0.0"

Highlights

For more detailed API examples, see API Examples.

• Familiar API: Most APIs are designed to mirror their counterparts in the standard library.
  • Vecx behaves like std::collections::Vec.
  • Mapx behaves like std::collections::HashMap.
  • MapxOrd behaves like std::collections::BTreeMap.
• Persistent Storage: Data is automatically saved to disk and loaded on instantiation.
• Typed Keys and Values: Keys and values are strongly typed and automatically serialized/deserialized.

Features

• fjall_backend: (Default) Use fjall as the backend database. Pure Rust implementation.
• rocks_backend: Use rocksdb as the backend database. C++ implementation.
• msgpack_codec: (Default) Use rmp-serde as the codec for faster performance.
• json_codec: Use serde_json as the codec for better compatibility.
• compress: (Default) Enable data compression in the backend database.

Usage

Vecx

Vecx is a persistent, vector-like data structure.

use vsdb::Vecx;

let mut vec = Vecx::new();

// Push some values
vec.push(&10);
vec.push(&20);
vec.push(&30);

// Get a value
assert_eq!(vec.get(1), Some(20));

// Iterate over the values
for value in vec.iter() {
    println!("{}", value);
}

// Pop a value
assert_eq!(vec.pop(), Some(30));
assert_eq!(vec.len(), 2);

Mapx

Mapx is a persistent, hash map-like data structure.

use vsdb::Mapx;

let mut map = Mapx::new();

// Insert some key-value pairs
map.insert(&"key1", &"value1");
map.insert(&"key2", &"value2");

// Get a value
assert_eq!(map.get(&"key1"), Some("value1".to_string()));

// Check if a key exists
assert!(map.contains_key(&"key2"));

// Iterate over the key-value pairs
for (key, value) in map.iter() {
    println!("{}: {}", key, value);
}

// Remove a key-value pair
map.remove(&"key1");
assert_eq!(map.len(), 1);

MapxOrd

MapxOrd is a persistent, B-tree map-like data structure that keeps keys in sorted order.

use vsdb::MapxOrd;

let mut map = MapxOrd::new();

// Insert some key-value pairs
map.insert(&3, &"three");
map.insert(&1, &"one");
map.insert(&2, &"two");

// Get a value
assert_eq!(map.get(&1), Some("one".to_string()));

// Iterate over the key-value pairs in sorted order
for (key, value) in map.iter() {
    println!("{}: {}", key, value);
}

// Get the first and last key-value pairs
assert_eq!(map.first(), Some((1, "one".to_string())));
assert_eq!(map.last(), Some((3, "three".to_string())));

Important Notes

• The serialized result of a vsdb instance cannot be used for distributed consensus. The serialized data contains meta-information (like storage paths) that may differ across environments. The correct approach is to read the required data and then process the raw content.
• The len() of a data structure is not always guaranteed to be absolutely reliable and should be treated as a hint. This is because some operations may not update the length atomically in real-time for performance reasons.

License

This project is licensed under the GPL-3.0 license.