Struct Db 

pub struct Db {
    pub objects: ObjectStore,
    pub id_index: IdIndex,
    pub sorted_indexes: SortedIndexes,
    pub graph: GraphStore,
    pub root: PathBuf,
    pub seq: AtomicU64,
    pub startup_ready: Arc<AtomicBool>,
    /* private fields */
}

Fields

objects: ObjectStore

id_index: IdIndex

sorted_indexes: SortedIndexes

graph: GraphStore

root: PathBuf

seq: AtomicU64

startup_ready: Arc<AtomicBool>

True once startup is fully ready (MANIFEST loaded or cold scan complete). Warm starts set this true before returning from open(). Cold starts set this true in the background thread when scan completes. Writes are held with 503 until this is true; reads always proceed.

Implementations

impl Db

pub fn in_memory() -> Self

Create a pure in-memory database — no disk I/O, no migration, instant startup. Perfect for tests, hot-cache layers, and ephemeral sessions. All data is lost when the Db is dropped.

pub fn open(db_root: &Path, dek: Option<Dek>) -> Result<Self>

Open (or create) a database. Runs v1→v2 migration automatically if log.aof is present.

pub fn start_cold_scan(self_arc: Arc<Self>)

Call this from Manager::open_all() after Arc::new(db). Spawns the cold scan background thread with stable heap addresses. No-op if startup is already complete (warm start).

pub fn put( &self, coll: &str, id: &str, data: Value, caused_by: Vec<String>, valid_from: Option<String>, valid_to: Option<String>, ) -> Result<Node>

Write a document. Returns the new node with its content hash set.

pub fn put_batch( &self, ops: Vec<(String, String, Value, Vec<String>, Option<String>, Option<String>)>, ) -> Result<Vec<Node>>

Batch put: write N documents in parallel, preserving monotonic seq ordering. Pre-allocates N seq numbers atomically, then parallelises object writes and id-index updates via Rayon. Each op is independent — safe to parallelise. Returns nodes in input order with assigned seq numbers.

pub fn flush_all(&self)

Flush both the id-index WAL and MANIFEST. Used on graceful shutdown.

pub fn compact(&self) -> Result<CompactStats>

Compact the v3 packed object store: keep the CURRENT version of every document (from the id-index) and reclaim everything else. No-op unless running with the v3 segment substrate (--dag-v3 / NEDB_DAG_V3).

This is a PRUNING operation: superseded/historical object versions are dropped, so AS OF / TRACE over pruned versions is discarded — that is what reclaims the space. Flushes first so all data is durable on disk before the old segments are deleted.

pub fn flush_manifest_if_dirty(&self)

Flush MANIFEST to disk if dirty. No-op for in-memory databases.

pub fn flush_manifest(&self)

Atomically persist current seq+head to MANIFEST. No-op for in-memory databases.

pub fn start_manifest_ticker(self_arc: Arc<Self>, interval_ms: u64)

Start a background thread that flushes both the id-index WAL and MANIFEST every interval_ms milliseconds. Call this after Arc::new(db) — the Arc keeps Db alive for the thread’s lifetime.

pub fn head(&self) -> String

Return the current Merkle head string. O(1) — read from cache.

pub fn delete(&self, coll: &str, id: &str) -> Result<bool>

Delete a document — writes a tombstone node and removes the id from the index. The object history is preserved in the DAG; only the live id pointer is cleared.

pub fn get(&self, coll: &str, id: &str) -> Option<Node>

Get the current version of a document by id.

pub fn get_by_hash(&self, hash: &str) -> Option<Node>

Get a specific version of a document by object hash.

pub fn get_as_of(&self, coll: &str, id: &str, target_seq: u64) -> Option<Node>

Get a document AS OF a specific sequence number. Walks the version chain (prev links) backward until seq <= target.

pub fn list(&self, coll: &str) -> Vec<Node>

List all documents in a collection, returning current versions.

pub fn order_by_asc(&self, coll: &str, field: &str, limit: usize) -> Vec<Node>

ORDER BY field ASC LIMIT n — uses sorted index if available, else falls back to full scan.

pub fn order_by_desc(&self, coll: &str, field: &str, limit: usize) -> Vec<Node>

ORDER BY field DESC LIMIT n

pub fn trace(&self, hash: &str, reverse: bool, limit: usize) -> Vec<Node>

TRACE caused_by — walk causal graph from a node.

pub fn verify(&self) -> (usize, Vec<String>)

Verify tamper-evidence of all objects.

pub fn create_sorted_index(&self, coll: &str, field: &str)

Create a sorted index for a (coll, field) pair.

pub fn get_hash_by_seq(&self, seq: u64) -> Option<String>

Resolve a sequence number to its content hash (v1 compatibility). Only covers nodes written in the current process session + cold-scan nodes.

pub fn link(&self, frm: &str, rel: &str, to: &str) -> Result<()>

Add an explicit named relation edge between two documents. Add an explicit named relation between two “coll:id” nodes. Relations stored as links documents — NQL-queryable, time-travelable, consistent with the PyO3 binding which uses the same links convention.

pub fn unlink(&self, frm: &str, rel: &str, to: &str) -> Result<bool>

Remove a named relation (deletes the links document).

pub fn neighbors(&self, frm: &str, rel: &str) -> Vec<Node>

Get neighbor nodes via a named relation. Queries links — consistent with the PyO3 binding.

Trait Implementations

impl Drop for Db

fn drop(&mut self)

Flush buffered state when the database is closed so a write-then-drop sequence is durable without an explicit flush_all().

IdIndex::set only stages updates in the in-memory WAL write_buf; disk persistence happens in flush_write_buf(), normally driven by the manifest ticker. A short-lived Db (a library user’s { let db = Db::open(p)?; db.put(..)?; } block, or a test) has no ticker, so without this its writes would be silently lost on reopen. Flushing on drop mirrors the flush-on-close contract of other embedded stores (sled, RocksDB).

In production this is a harmless safety net, not the primary durability path: the manifest ticker thread holds an Arc<Db> for the process lifetime, so Drop only fires once every owning handle is gone. No-op for in-memory databases (flush_all short-circuits on :memory:).

fn pin_drop(self: Pin<&mut Self>)

🔬This is a nightly-only experimental API. (pin_ergonomics)

Execute the destructor for this type, but different to Drop::drop, it requires self to be pinned.