Crate vsdb 

vsdb

vsdb is a high-performance, embedded database designed to feel like using Rust’s standard collections. It provides persistent, disk-backed data structures — Mapx (a HashMap-like map), MapxOrd (a BTreeMap-like ordered map), VerMap (Git-model versioned storage with branching, commits, and merge), MptCalc / SmtCalc (stateless Merkle trie implementations), VerMapWithProof (versioned storage with Merkle root computation), SlotDex (skip-list-like index for paged queries), and VecDex (approximate nearest-neighbor vector index via HNSW).

This crate is the primary entry point for most users.

Read-only mode

Configure read-only access before any other VSDB API, then restore handles saved by a writable process:

use vsdb::{InstanceId, Mapx, VsdbOptions, vsdb_configure};

vsdb_configure(VsdbOptions::read_only("/srv/my-app/vsdb"))?;
let id: InstanceId = "40960000".parse()?;
let map = Mapx::<String, String>::from_meta(id)?;
assert!(map.namespace().is_read_only());

The setting is one-shot and process-wide, including every namespace. Query APIs and in-memory WAL recovery leave the database tree unchanged; creation and mutation are unavailable.

Why core collections don’t have len()

Mapx, MapxOrd, and other core primitives do not maintain durable count metadata and intentionally omit len(). The engine supports atomic multi-key batches within one collection prefix, but VSDB does not expose a cross-prefix batch for pairing a map write with a separate counter. Independently updating such a counter can leave it inconsistent after a crash; aliases and raw writes would also need to participate in counting.

Higher-level structures (VecDex, SlotDex) do maintain a count because they fully control their own insert/remove paths: every mutation stages data and the durable count into one atomic engine write batch (StagedRows), so on-disk state stays consistent across crashes. Hydrate rebuilds only in-memory caches from those durable rows — there is no dirty-flag rebuild-on-recovery path.

Application-layer counting

If you need a count over a core collection, maintain it yourself:

use vsdb::MapxOrd;
use vsdb::{KeyEnDe, KeyEnDeOrdered, ValueEnDe};

struct CountedMap<K: KeyEnDe + KeyEnDeOrdered, V: ValueEnDe> {
    map: MapxOrd<K, V>,
    count: usize,  // in-memory; rebuild on restart
}

impl<K: KeyEnDe + KeyEnDeOrdered + Ord, V: ValueEnDe> CountedMap<K, V> {
    fn insert(&mut self, key: &K, value: &V) {
        if !self.map.contains_key(key) {
            self.count += 1;
        }
        self.map.insert(key, value);
    }

    fn remove(&mut self, key: &K) {
        if self.map.contains_key(key) {
            self.count -= 1;
        }
        self.map.remove(key);
    }

    fn len(&self) -> usize { self.count }

    /// Rebuild from disk after an unclean shutdown.
    fn rebuild_count(&mut self) {
        self.count = self.map.iter().count();
    }
}

Re-exports

pub use basic::mapx::Mapx;

pub use basic::mapx_ord::MapxOrd;

pub use basic::mapx_ord_rawkey::MapxOrdRawKey;

pub use basic::orphan::Orphan;

pub use common::ende::KeyEnDe;

pub use common::ende::KeyEnDeOrdered;

pub use common::ende::ValueEnDe;

pub use versioned::BranchId;

pub use versioned::Commit;

pub use versioned::CommitId;

pub use versioned::DiffEntry;

pub use versioned::Snapshot;

pub use versioned::map::VerMap;

pub use dagmap::DagMapId;

pub use dagmap::raw::DagMapRaw;

pub use dagmap::rawkey::DagMapRawKey;

pub use trie::MptCalc;

pub use trie::MptProof;

pub use trie::ProofWithRoot;

pub use trie::SmtCalc;

pub use trie::SmtProof;

pub use trie::TrieCalc;

pub use trie::VerMapWithProof;

pub use slotdex::SlotDex;

pub use slotdex::SlotDex32;

pub use slotdex::SlotDex64;

pub use slotdex::SlotDex128;

pub use slotdex::SlotType;

pub use vecdex::HnswConfig;

pub use vecdex::VecDex;

pub use vecdex::VecDexCosine;

pub use vecdex::VecDexCosineF64;

pub use vecdex::VecDexDyn;

pub use vecdex::VecDexL2;

pub use vecdex::VecDexL2F64;

pub use vecdex::distance::Cosine;

pub use vecdex::distance::DistanceMetric;

pub use vecdex::distance::InnerProduct;

pub use vecdex::distance::L2;

pub use vecdex::distance::MetricKind;

pub use vecdex::distance::Scalar;

pub use basic::persistent_btree::PersistentBTree;

pub use vsdb_core;

Modules

basic

User-facing, typed data structures (e.g., Mapx, MapxOrd).

common

Common Components

dagmap

Data structures for representing directed acyclic graphs (DAGs).

slotdex

Skip-list-like index for efficient, timestamp-based paged queries. Slot-based index for efficient, timestamp-based paged queries.

trie

Lightweight, stateless Merkle trie implementations (MPT + SMT). Lightweight, stateless Merkle trie implementations.

vecdex

Approximate nearest-neighbor vector index (HNSW algorithm). Approximate nearest-neighbor vector index backed by the HNSW algorithm.

versioned

Git-model versioned storage: branches, commits, merge, and history.

Structs

InstanceId

Commonly used items, re-exported for convenience.

Namespace

Commonly used items, re-exported for convenience.

NamespaceOpts

Commonly used items, re-exported for convenience.

NsInfo

Commonly used items, re-exported for convenience.

VsdbOptions

Commonly used items, re-exported for convenience.

Enums

OpenMode

Commonly used items, re-exported for convenience.

VsdbError

Structured error type for all VSDB public API operations.

Constants

DEFAULT_NS_ID

Commonly used items, re-exported for convenience.

Functions

vsdb_configure

Commonly used items, re-exported for convenience.

vsdb_flush

Commonly used items, re-exported for convenience.

vsdb_get_base_dir

Commonly used items, re-exported for convenience.

vsdb_get_custom_dir

Commonly used items, re-exported for convenience.

vsdb_open_mode

Commonly used items, re-exported for convenience.

Type Aliases

NsId

Commonly used items, re-exported for convenience.

Result

Alias for std::result::Result<T, VsdbError>.