Struct Immutable 

pub struct Immutable<F: Family, E: Context, K: Key, V: ValueEncoding, C: Mutable<Item = Operation<F, K, V>> + Persistable<Error = Error>, H: CHasher, T: Translator, S: Strategy>
where
    C::Item: EncodeShared,
{ /* private fields */ }

An authenticated database that only supports adding new keyed values (no updates or deletions).

Invariant

A key must be set at most once across the database history. Writing the same key more than once is undefined behavior.

Use fixed::Db or variable::Db for concrete instantiations.

Implementations

impl<F, E, K, V, C, H, T, S> Immutable<F, E, K, V, C, H, T, S>

where F: Family, E: Context, K: Key, V: ValueEncoding, C: Mutable<Item = Operation<F, K, V>> + Persistable<Error = Error>, C::Item: EncodeShared, H: CHasher, T: Translator, S: Strategy,

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

Create an initial MerkleizedBatch from the committed DB state.

impl<F: Family, E: Storage + Clock + Metrics, K: Array, V: FixedValue, H: Hasher, T: Translator, S: Strategy> Immutable<F, E, K, FixedEncoding<V>, Journal<E, Operation<F, K, FixedEncoding<V>>>, H, T, S>

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

Returns a Db 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: Storage + Clock + Metrics, K: Key, V: VariableValue, H: Hasher, T: Translator, S: Strategy> Immutable<F, E, K, VariableEncoding<V>, Journal<E, Operation<F, K, VariableEncoding<V>>>, H, T, S>

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

Returns a Db 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, E, K, V, C, H, T, S> Immutable<F, E, K, V, C, H, T, S>

where F: Family, E: Context, K: Key, V: ValueEncoding, C: Mutable<Item = Operation<F, K, V>> + Persistable<Error = Error>, C::Item: EncodeShared, H: CHasher, T: Translator, S: Strategy,

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

Return the inactivity floor location declared by the last committed batch.

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

Return the Location of the next operation appended to this db.

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 const fn sync_boundary(&self) -> Location<F>

Return the most recent location from which this database can safely be synced, and the upper bound on Self::prune’s loc. For immutable databases, this equals the inactivity floor declared by the last committed batch.

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 or its corresponding operation has been pruned.

pub async fn get_many( &self, keys: &[&K], ) -> Result<Vec<Option<V::Value>>, Error<F>>

Batch read multiple keys.

Returns results in the same order as the input keys.

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

Get the metadata associated with the last commit.

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

Analogous to proof but with respect to the state of the database when it had op_count operations.

Contract

op_count must be a commit-boundary size: the operation at op_count - 1 must itself be a commit op. Non-commit-boundary sizes are not supported because the inactivity floor governing them is not directly retrievable.

Errors

Returns crate::merkle::Error::LocationOverflow if op_count or start_loc > crate::merkle::Family::MAX_LEAVES. Returns crate::merkle::Error::RangeOutOfBounds if op_count > number of operations, or if start_loc >= op_count. Returns Error::OperationPruned if start_loc has been pruned. Returns Error::HistoricalFloorPruned if op_count - 1 is retained but is not a commit op, either because the caller passed a non-commit-boundary op_count or because pruning removed the commit that would have governed op_count.

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

Generate and return:

1. a proof of all operations applied to the db in the range starting at (and including) location start_loc, and ending at the first of either:
   • the last operation performed, or
   • the operation max_ops from the start.
2. the operations corresponding to the leaves in this range.

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

Prune operations prior to prune_loc. This does not affect the db’s root, but it will affect retrieval of any keys that were set prior to prune_loc.

Pruning is irreversible. Callers must ensure any floor-raising batch has been durably committed (via Immutable::commit or Immutable::sync) before pruning. The inactivity floor used to gate pruning is updated by Immutable::apply_batch before the batch is durable. If the batch is lost on crash, recovery replays from the prior durable floor, which may reference data that has already been pruned.

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 both the operations journal and its Merkle structure to the historical state at size, and removes rewound set operations from the in-memory snapshot.

Errors

Returns an error when:

• size is not a valid rewind target
• the target’s required logical range is not fully retained (for immutable, this means the oldest retained location is already beyond the rewind boundary)
• size - 1 is not a commit operation

Any error from this method is fatal for this handle. Rewind may mutate journal state before this method finishes rebuilding in-memory rewind state. 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 Immutable::commit or Immutable::sync.

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

Return the canonical QMDB root of the db.

pub const fn strategy(&self) -> &S

Return a reference to the merkleization strategy.

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

Return the pinned Merkle nodes at the given location.

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

Sync all database state to disk. While this isn’t necessary to ensure durability of committed operations, periodic invocation may reduce memory usage and the time required to recover the database on restart.

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

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

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

Destroy the db, removing all data from disk.

pub fn new_batch(&self) -> UnmerkleizedBatch<F, H, K, V, S>

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

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

Apply a batch::MerkleizedBatch to the database.

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.

Returns the range of locations written.

Errors

• Error::StaleBatch if the batch was created from a stale DB state.
• Error::FloorRegressed if any commit in the chain (the tip or any unapplied ancestor) declares an inactivity floor below the previous commit’s floor (or, for the oldest unapplied commit, below the database’s current floor).
• Error::FloorBeyondSize if any commit in the chain (the tip or any unapplied ancestor) declares an inactivity floor that exceeds its own commit operation’s location. The maximum valid floor for a commit is its own location; a floor past the commit would permit pruning the commit itself.

On any floor error, the database state is unchanged.

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