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.

Why core collections don’t have len()

The underlying LSM-Tree engine (mmdb) does not support atomic “write data + update count” across different keys. A process crash between the two leaves them inconsistent — downstream code that trusts the count for index arithmetic will panic. For this reason Mapx, MapxOrd, and other core primitives intentionally omit len().

Higher-level structures (VecDex, SlotDex) do maintain a count because they fully control their own insert/remove paths. A dirty-flag mechanism automatically rebuilds the count from live data on recovery after an unclean shutdown.

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::NO_COMMIT;

pub use versioned::diff::DiffEntry;

pub use versioned::handle::Branch;

pub use versioned::handle::BranchMut;

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::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

The complete public identity of a collection instance — the same shape at every layer: in-memory comparison, the persisted meta bytes, and this token. ns: None ⇔ default namespace ⇔ the 16-byte meta form; a bare u64 converts losslessly (From<u64> ⇒ ns: None).

Namespace

A cheap, cloneable handle to an engine instance (an anonymous placement group). See the module docs for the design rules.

NamespaceOpts

Creation-time options; persisted in the registry. Everything is defaulted — this struct exists for the advanced tier.

NsInfo

A registry entry as reported by vsdb_ns_list.

Enums

VsdbError

Structured error type for all VSDB public API operations.

Constants

DEFAULT_NS_ID

The default namespace’s id — a fixed constant, never allocated, never present in the registry, never looked up.

Functions

vsdb_flush

Flushes all data to disk — the default namespace and every open non-default namespace.

vsdb_get_base_dir

Returns the base directory path for VSDB.

vsdb_ns_close

Closes an open namespace, releasing all of its resources: engine memory, compaction threads, fds, and mmdb LOCK files. The active memtables are flushed and the WALs synced first (errors surface here, unlike a plain drop).

vsdb_ns_destroy

Destroys a namespace: removes its registry entry, then deletes its whole directory tree — O(1) bulk reclaim.

vsdb_ns_list

Lists every registered (non-default) namespace.

vsdb_ns_relocate

Re-points a namespace at a new root directory (e.g. after moving a volume). Updates the registry only — moving the data is the operator’s job, done before calling this. A target that does not already hold an initialized dataset (format marker + per-shard engine anchors) is refused: repointing at it would durably orphan the real data behind a silent success. Whether it is the right dataset cannot be verified — roots carry no namespace id.

vsdb_set_base_dir

Sets the base directory path for VSDB manually.

Type Aliases

NsId

A namespace identifier: small, stable, allocated once at creation, never reused.

Result

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