Struct Db 

pub struct Db<F: Family, E: Context, C: Contiguous<Item: CodecShared>, I: UnorderedIndex<Value = Location<F>>, H: Hasher, U: Send + Sync> { /* private fields */ }

An “Any” QMDB implementation generic over ordered/unordered keys and variable/fixed values. Consider using one of the following specialized variants instead, which may be more ergonomic:

• crate::qmdb::any::ordered::fixed::Db
• crate::qmdb::any::ordered::variable::Db
• crate::qmdb::any::unordered::fixed::Db
• crate::qmdb::any::unordered::variable::Db

Implementations

impl<F, E, C, I, H, U> Db<F, E, C, I, H, U>

where F: Family, E: Context, U: Update + Send + Sync, C: Contiguous<Item = Operation<F, U>>, I: UnorderedIndex<Value = Location<F>>, H: Hasher, Operation<F, U>: Codec,

pub fn new_batch(&self) -> UnmerkleizedBatch<F, H, U>

Create a new speculative batch of operations with this database as its parent.

impl<F, E, C, I, H, U> Db<F, E, C, I, H, U>

where F: Family, E: Context, U: Update + Send + Sync + 'static, C: Mutable<Item = Operation<F, U>> + Persistable<Error = Error>, I: UnorderedIndex<Value = Location<F>>, H: Hasher, Operation<F, U>: Codec,

pub async fn apply_batch( &mut self, batch: Arc<MerkleizedBatch<F, H::Digest, U>>, ) -> Result<Range<Location<F>>, Error<F>>

Apply a batch to the database, returning the range of written operations.

A batch is valid only if every batch applied to the database since this batch’s ancestor chain was created is an ancestor of this batch. Applying a batch from a different fork returns crate::qmdb::Error::StaleBatch.

This publishes the batch to the in-memory database state and appends it to the journal, but does not durably persist it. Call Db::commit or Db::sync to guarantee durability.

impl<F: Family, E, C, I, H, U> Db<F, E, C, I, H, U>

where E: Context, U: Update + Send + Sync, C: Contiguous<Item = Operation<F, U>>, I: UnorderedIndex<Value = Location<F>>, H: Hasher, Operation<F, U>: Codec,

pub fn to_batch(&self) -> Arc<MerkleizedBatch<F, H::Digest, U>>

Create an initial MerkleizedBatch from the committed DB state.

This is the starting point for building owned batch chains.

impl<F, E, U, C, I, H> Db<F, E, C, I, H, U>

where F: Family, E: Context, U: Update, C: Contiguous<Item = Operation<F, U>>, I: UnorderedIndex<Value = Location<F>>, H: Hasher, Operation<F, U>: Codec,

pub const fn inactivity_floor_loc(&self) -> Location<F>

Return the inactivity floor location. This is the location before which all operations are known to be inactive. Operations before this point can be safely pruned.

pub const fn is_empty(&self) -> bool

Whether the snapshot currently has no active keys.

pub async fn get_metadata(&self) -> Result<Option<U::Value>, Error<F>>

Get the metadata associated with the last commit.

pub fn root(&self) -> H::Digest

pub async fn get(&self, key: &U::Key) -> Result<Option<U::Value>, Error<F>>

Get the value of key in the db, or None if it has no value.

pub async fn bounds(&self) -> Range<Location<F>>

Return [start, end) where start and end - 1 are the Locations of the oldest and newest retained operations respectively.

pub async fn pinned_nodes_at( &self, loc: Location<F>, ) -> Result<Vec<H::Digest>, Error<F>>

Return the pinned Merkle nodes for a lower operation boundary of loc.

impl<F, E, U, C, I, H> Db<F, E, C, I, H, U>

where F: Family, E: Context, U: Update, C: Mutable<Item = Operation<F, U>>, I: UnorderedIndex<Value = Location<F>>, H: Hasher, Operation<F, U>: Codec,

pub async fn prune(&mut self, prune_loc: Location<F>) -> Result<(), Error<F>>

Prunes historical operations prior to prune_loc. This does not affect the db’s root or snapshot.

Errors

• Returns crate::qmdb::Error::PruneBeyondMinRequired if prune_loc > inactivity floor.
• Returns crate::merkle::Error::LocationOverflow if prune_loc > crate::merkle::Family::MAX_LEAVES.

pub async fn historical_proof( &self, historical_size: Location<F>, start_loc: Location<F>, max_ops: NonZeroU64, ) -> Result<(Proof<F, H::Digest>, Vec<Operation<F, U>>), Error<F>>

pub async fn proof( &self, loc: Location<F>, max_ops: NonZeroU64, ) -> Result<(Proof<F, H::Digest>, Vec<Operation<F, U>>), Error<F>>

pub async fn rewind( &mut self, size: Location<F>, ) -> Result<Vec<Location<F>>, Error<F>>

Rewind the database to size operations, where size is the location of the next append.

This rewinds both the authenticated log and the in-memory snapshot, then restores metadata (last_commit_loc, inactivity_floor_loc, active_keys) for the new tip commit.

Errors

Returns an error when:

• size is not a valid rewind target
• the target’s required logical range is not fully retained (for example, the target inactivity floor is pruned)
• size - 1 is not a commit operation

Any error from this method is fatal for this handle. Rewind may mutate journal state before all in-memory structures are rebuilt. Callers must drop this database handle after any Err from rewind and reopen from storage.

Returns the list of locations restored to active state in the snapshot.

A successful rewind is not restart-stable until a subsequent Db::commit or Db::sync.

impl<F, E, U, C, I, H> Db<F, E, C, I, H, U>

where F: Family, E: Context, U: Update, C: Mutable<Item = Operation<F, U>> + Persistable<Error = Error>, I: UnorderedIndex<Value = Location<F>>, H: Hasher, Operation<F, U>: Codec,

pub async fn init_from_log<Cb>( index: I, log: Journal<F, E, C, H>, known_inactivity_floor: Option<Location<F>>, callback: Cb, ) -> Result<Self, Error<F>>

where Cb: FnMut(bool, Option<Location<F>>),

Returns a Db initialized from log, using callback to report snapshot building events.

Panics

Panics if the log is empty or the last operation is not a commit floor operation.

pub async fn sync(&self) -> Result<(), Error<F>>

Sync all database state to disk.

pub async fn commit(&self) -> Result<(), Error<F>>

Durably commit the journal state published by prior Db::apply_batch calls.

pub async fn destroy(self) -> Result<(), Error<F>>

Destroy the db, removing all data from disk.

impl<F: Family, E: Context, K: Array, V: FixedValue, H: Hasher, T: Translator, const P: usize> Db<F, E, Journal<E, Operation<F, Update<K, FixedEncoding<V>>>>, Index<T, Location<F>, P>, H, Update<K, FixedEncoding<V>>>

pub async fn init(context: E, cfg: Config<T>) -> Result<Self, Error<F>>

Returns a Db QMDB initialized from cfg. Uncommitted log operations will be discarded and the state of the db will be as of the last committed operation.

impl<F: Family, E: Context, K: Array, V: FixedValue, H: Hasher, T: Translator> Db<F, E, Journal<E, Operation<F, Update<K, FixedEncoding<V>>>>, Index<T, Location<F>>, H, Update<K, FixedEncoding<V>>>

pub async fn init(context: E, cfg: Config<T>) -> Result<Self, Error<F>>

Returns a Db qmdb initialized from cfg. Any uncommitted log operations will be discarded and the state of the db will be as of the last committed operation.

impl<F: Family, E: Context, K: Key, V: VariableValue, H: Hasher, T: Translator, const P: usize> Db<F, E, Journal<E, Operation<F, Update<K, VariableEncoding<V>>>>, Index<T, Location<F>, P>, H, Update<K, VariableEncoding<V>>>

where Operation<F, K, V>: Codec,

pub async fn init( context: E, cfg: VariableConfig<T, <Operation<F, K, V> as Read>::Cfg>, ) -> Result<Self, Error<F>>

Returns a Db QMDB initialized from cfg. Uncommitted log operations will be discarded and the state of the db will be as of the last committed operation.

impl<F: Family, E: Context, K: Key, V: VariableValue, H: Hasher, T: Translator> Db<F, E, Journal<E, Operation<F, Update<K, VariableEncoding<V>>>>, Index<T, Location<F>>, H, Update<K, VariableEncoding<V>>>

where Operation<F, K, V>: Codec,

pub async fn init( context: E, cfg: VariableConfig<T, <Operation<F, K, V> as Read>::Cfg>, ) -> Result<Self, Error<F>>

Returns a Db QMDB initialized from cfg. Any uncommitted log operations will be discarded and the state of the db will be as of the last committed operation.

impl<F: Family, E: Context, K: Key, V: ValueEncoding, C: Contiguous<Item = Operation<F, K, V>>, I: Index<Value = Location<F>>, H: Hasher> Db<F, E, C, I, H, Update<K, V>>

where Operation<F, K, V>: Codec,

pub fn span_contains(span_start: &K, span_end: &K, key: &K) -> bool

Whether the span defined by span_start and span_end contains key.

pub async fn get_span( &self, key: &K, ) -> Result<Option<(Location<F>, Update<K, V>)>, Error<F>>

Get the operation that defines the span whose range contains key, or None if the DB is empty.

pub async fn get_all(&self, key: &K) -> Result<Option<(V::Value, K)>, Error<F>>

Get the (value, next-key) pair of key in the db, or None if it has no value.

pub async fn stream_range<'a>( &'a self, start: K, ) -> Result<impl Stream<Item = Result<(K, V::Value), Error<F>>> + 'a, Error<F>>

where V: 'a,

Streams all active (key, value) pairs in the database in key order, starting from the first active key greater than or equal to start.

impl<F: Family, E: Context, K: Array, V: FixedValue, H: Hasher, T: Translator, const P: usize> Db<F, E, Journal<E, Operation<F, Update<K, FixedEncoding<V>>>>, Index<T, Location<F>, P>, H, Update<K, FixedEncoding<V>>>

pub async fn init(context: E, cfg: Config<T>) -> Result<Self, Error<F>>

Returns a Db QMDB initialized from cfg. Uncommitted log operations will be discarded and the state of the db will be as of the last committed operation.

impl<F: Family, E: Context, K: Array, V: FixedValue, H: Hasher, T: Translator> Db<F, E, Journal<E, Operation<F, Update<K, FixedEncoding<V>>>>, Index<T, Location<F>>, H, Update<K, FixedEncoding<V>>>

pub async fn init(context: E, cfg: Config<T>) -> Result<Self, Error<F>>

Returns a Db QMDB initialized from cfg. Uncommitted log operations will be discarded and the state of the db will be as of the last committed operation.

impl<F: Family, E: Context, K: Key, V: VariableValue, H: Hasher, T: Translator, const P: usize> Db<F, E, Journal<E, Operation<F, Update<K, VariableEncoding<V>>>>, Index<T, Location<F>, P>, H, Update<K, VariableEncoding<V>>>

where Operation<F, K, V>: Codec,

pub async fn init( context: E, cfg: VariableConfig<T, <Operation<F, K, V> as Read>::Cfg>, ) -> Result<Self, Error<F>>

Returns a Db QMDB initialized from cfg. Uncommitted log operations will be discarded and the state of the db will be as of the last committed operation.

impl<F: Family, E: Context, K: Key, V: VariableValue, H: Hasher, T: Translator> Db<F, E, Journal<E, Operation<F, Update<K, VariableEncoding<V>>>>, Index<T, Location<F>>, H, Update<K, VariableEncoding<V>>>

where Operation<F, K, V>: Codec,

pub async fn init( context: E, cfg: VariableConfig<T, <Operation<F, K, V> as Read>::Cfg>, ) -> Result<Self, Error<F>>

Returns a Db QMDB initialized from cfg. Uncommitted log operations will be discarded and the state of the db will be as of the last committed operation.

Trait Implementations

impl<F, E, U, C, I, H> Persistable for Db<F, E, C, I, H, U>

where F: Family, E: Context, U: Update, C: Mutable<Item = Operation<F, U>> + Persistable<Error = Error>, I: UnorderedIndex<Value = Location<F>>, H: Hasher, Operation<F, U>: Codec,

type Error = Error<F>

The error type returned when there is a failure from the underlying storage system.

async fn commit(&self) -> Result<(), Error<F>>

Durably persist the structure, guaranteeing the current state will survive a crash.

async fn sync(&self) -> Result<(), Error<F>>

Durably persist the structure, guaranteeing the current state will survive a crash, and that no recovery will be needed on startup.

async fn destroy(self) -> Result<(), Error<F>>

Destroy the structure, removing all associated storage.