Struct Db 

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

A Current QMDB implementation generic over ordered/unordered keys and variable/fixed values.

Implementations

impl<F, E, C, I, H, U, const N: usize> Db<F, E, C, I, H, U, N>

where F: Graftable, 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, N>>

Create an initial MerkleizedBatch from the committed DB state.

impl<F, E, C, I, H, U, const N: usize> Db<F, E, C, I, H, U, N>

where F: Graftable, 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 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 fn verify_range_proof( hasher: &mut H, proof: &RangeProof<F, H::Digest>, start_loc: Location<F>, ops: &[Operation<F, U>], chunks: &[[u8; N]], root: &H::Digest, ) -> bool

Return true if the given sequence of ops were applied starting at location start_loc in the log with the provided root, having the activity status described by chunks.

impl<F, E, U, C, I, H, const N: usize> Db<F, E, C, I, H, U, N>

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

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

Returns the canonical root. See the Root structure section in the module documentation.

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

Returns the ops tree root.

This is the root of the raw operations log, without the activity bitmap. It is used as the sync target because the sync engine verifies batches against the ops root, not the canonical root.

See the Root structure section in the module documentation.

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

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

pub async fn range_proof( &self, hasher: &mut H, start_loc: Location<F>, max_ops: NonZeroU64, ) -> Result<(RangeProof<F, H::Digest>, Vec<Operation<F, U>>, Vec<[u8; N]>), Error<F>>

Returns a proof that the specified range of operations are part of the database, along with the operations from the range. A truncated range (from hitting the max) can be detected by looking at the length of the returned operations vector. Also returns the bitmap chunks required to verify the proof.

Errors

Returns Error::OperationPruned if start_loc falls in a pruned bitmap chunk. Returns crate::merkle::Error::LocationOverflow if start_loc > crate::merkle::Family::MAX_LEAVES. Returns crate::merkle::Error::RangeOutOfBounds if start_loc >= number of leaves in the tree.

impl<F, E, U, C, I, H, const N: usize> Db<F, E, C, I, H, U, N>

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

pub async fn ops_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>>

Returns an ops-level historical proof for the specified range.

Unlike range_proof which returns grafted proofs incorporating the activity bitmap, this returns standard range proofs suitable for state sync.

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

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

pub fn flatten(&mut self)

Collapse the accumulated bitmap Layer chain into a flat Base.

Each Db::apply_batch pushes a new Layer on the bitmap. These layers are cheap to create but make subsequent reads walk the full chain. Calling flatten collapses the chain into a single Base, bounding lookup cost.

This is called automatically by Db::prune. Callers that apply many batches without pruning should call this periodically.

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 Error::PruneBeyondMinRequired if prune_loc > inactivity floor.
• Returns crate::merkle::Error::LocationOverflow if prune_loc > crate::merkle::Family::MAX_LEAVES.

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

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

This rewinds the underlying Any database and rebuilds the Current overlay state (bitmap, grafted tree, and canonical root) for the rewound size.

Errors

Returns an error when:

• size is not a valid rewind target
• the target’s required logical range is not fully retained (for Current, this includes the underlying Any inactivity-floor boundary and bitmap pruning boundary)
• size - 1 is not a commit operation
• size is below the bitmap pruning boundary

Any error from this method is fatal for this handle. Rewind may mutate state in the underlying Any database before this Current overlay finishes rebuilding. Callers must drop this database handle after any Err from rewind and reopen from storage.

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

impl<F, E, U, C, I, H, const N: usize> Db<F, E, C, I, H, U, N>

where F: Graftable, 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 commit(&self) -> Result<(), Error<F>>

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

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

Sync all database state to disk.

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

Destroy the db, removing all data from disk.

impl<F, E, U, C, I, H, const N: usize> Db<F, E, C, I, H, U, N>

where F: Graftable, E: Context, U: Update + '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, N>>, ) -> 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 Error::StaleBatch.

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

impl<F: Graftable, E: Context, C: Contiguous<Item = Operation<F, K, V>>, K: Key, V: ValueEncoding, I: OrderedIndex<Value = Location<F>>, H: Hasher, const N: usize> Db<F, E, C, I, H, Update<K, V>, N>

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

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

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

pub fn verify_key_value_proof( hasher: &mut H, key: K, value: V::Value, proof: &KeyValueProof<F, K, H::Digest, N>, root: &H::Digest, ) -> bool

Return true if the proof authenticates that key currently has value value in the db with the provided root.

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

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

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.

pub fn verify_exclusion_proof( hasher: &mut H, key: &K, proof: &ExclusionProof<F, K, V, H::Digest, N>, root: &H::Digest, ) -> bool

Return true if the proof authenticates that key does not exist in the db with the provided root.

impl<F: Graftable, E: Context, C: Mutable<Item = Operation<F, K, V>>, K: Key, V: ValueEncoding, I: OrderedIndex<Value = Location<F>>, H: Hasher, const N: usize> Db<F, E, C, I, H, Update<K, V>, N>

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

pub async fn key_value_proof( &self, hasher: &mut H, key: K, ) -> Result<KeyValueProof<F, K, H::Digest, N>, Error<F>>

Generate and return a proof of the current value of key, along with the other KeyValueProof required to verify the proof. Returns KeyNotFound error if the key is not currently assigned any value.

Errors

Returns Error::KeyNotFound if the key is not currently assigned any value.

pub async fn exclusion_proof( &self, hasher: &mut H, key: &K, ) -> Result<ExclusionProof<F, K, V, H::Digest, N>, Error<F>>

Generate and return a proof that the specified key does not exist in the db.

Errors

Returns Error::KeyExists if the key exists in the db.

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

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

Initializes a Db authenticated database from the given config. Leverages parallel Merkleization to initialize the bitmap Merkle tree if a thread pool is provided.

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

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

Initializes a Db from the given config. Leverages parallel Merkleization to initialize the bitmap Merkle tree if a thread pool is provided.

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

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

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

Initializes a Db from the given config. Leverages parallel Merkleization to initialize the bitmap Merkle tree if a thread pool is provided.

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

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

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

Initializes a Db from the given config. Leverages parallel Merkleization to initialize the bitmap Merkle tree if a thread pool is provided.

impl<F: Graftable, E: Context, C: Contiguous<Item = Operation<F, K, V>>, K: Array, V: ValueEncoding, I: UnorderedIndex<Value = Location<F>>, H: Hasher, const N: usize> Db<F, E, C, I, H, Update<K, V>, N>

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

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

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

pub fn verify_key_value_proof( hasher: &mut H, key: K, value: V::Value, proof: &KeyValueProof<F, H::Digest, N>, root: &H::Digest, ) -> bool

Return true if the proof authenticates that key currently has value value in the db with the provided root.

impl<F: Graftable, E: Context, C: Mutable<Item = Operation<F, K, V>>, K: Array, V: ValueEncoding, I: UnorderedIndex<Value = Location<F>>, H: Hasher, const N: usize> Db<F, E, C, I, H, Update<K, V>, N>

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

pub async fn key_value_proof( &self, hasher: &mut H, key: K, ) -> Result<KeyValueProof<F, H::Digest, N>, Error<F>>

Generate and return a proof of the current value of key, along with the other KeyValueProof required to verify the proof. Returns KeyNotFound error if the key is not currently assigned any value.

Errors

Returns Error::KeyNotFound if the key is not currently assigned any value.

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

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

Initializes a Db authenticated database from the given config. Leverages parallel Merkleization to initialize the bitmap Merkle tree if a thread pool is provided.

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

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

Initializes a Db authenticated database from the given config. Leverages parallel Merkleization to initialize the bitmap tree if a thread pool is provided.

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

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

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

Initializes a Db from the given config. Leverages parallel Merkleization to initialize the bitmap Merkle tree if a thread pool is provided.

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

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

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

Initializes a Db from the given config. Leverages parallel Merkleization to initialize the bitmap Merkle tree if a thread pool is provided.

Trait Implementations

impl<F, E, U, C, I, H, const N: usize> Persistable for Db<F, E, C, I, H, U, N>

where F: Graftable, 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.