Struct FinalizedState

pub struct FinalizedState {
    debug_stop_at_height: Option<Height>,
    pub db: ZebraDb,
    pub elastic_db: Option<Elasticsearch>,
    pub elastic_blocks: Vec<String>,
}

The finalized part of the chain state, stored in the db.

rocksdb allows concurrent writes through a shared reference, so clones of the finalized state represent the same database instance. When the final clone is dropped, the database is closed.

This is different from NonFinalizedState::clone(), which returns an independent copy of the chains.

Fields

debug_stop_at_height: Option<Height>

The configured stop height.

Commit blocks to the finalized state up to this height, then exit Zebra.

db: ZebraDb

The underlying database.

rocksdb allows reads and writes via a shared reference, so this database object can be freely cloned. The last instance that is dropped will close the underlying database.

elastic_db: Option<Elasticsearch>

The elasticsearch handle.

elastic_blocks: Vec<String>

A collection of blocks to be sent to elasticsearch as a bulk.

Implementations

impl FinalizedState

pub fn new(config: &Config, network: &Network, enable_elastic_db: bool) -> Self

Returns an on-disk database instance for config, network, and elastic_db. If there is no existing database, creates a new database on disk.

pub(crate) fn new_with_debug( config: &Config, network: &Network, debug_skip_format_upgrades: bool, enable_elastic_db: bool, read_only: bool, ) -> Self

Returns an on-disk database instance with the supplied production and debug settings. If there is no existing database, creates a new database on disk.

This method is intended for use in tests.

pub fn network(&self) -> Network

Returns the configured network for this database.

pub fn commit_finalized( &mut self, ordered_block: (CheckpointVerifiedBlock, Sender<Result<Hash, BoxError>>), prev_note_commitment_trees: Option<NoteCommitmentTrees>, ) -> Result<(CheckpointVerifiedBlock, NoteCommitmentTrees), BoxError>

Commit a checkpoint-verified block to the state.

It’s the caller’s responsibility to ensure that blocks are committed in order.

pub fn commit_finalized_direct( &mut self, finalizable_block: FinalizableBlock, prev_note_commitment_trees: Option<NoteCommitmentTrees>, source: &str, ) -> Result<(Hash, NoteCommitmentTrees), BoxError>

Immediately commit a finalized block to the finalized state.

This can be called either by the non-finalized state (when finalizing a block) or by the checkpoint verifier.

Use source as the source of the block in log messages.

Errors

• Propagates any errors from writing to the DB
• Propagates any errors from updating history and note commitment trees
• If hashFinalSaplingRoot / hashLightClientRoot / hashBlockCommitments does not match the expected value

pub fn elasticsearch(&mut self, block: &Arc<Block>)

Store finalized blocks into an elasticsearch database.

We use the elasticsearch bulk api to index multiple blocks at a time while we are synchronizing the chain, when we get close to tip we index blocks one by one.

fn is_at_stop_height(&self, block_height: Height) -> bool

Stop the process if block_height is greater than or equal to the configured stop height.

fn exit_process() -> !

Exit the host process.

Designed for debugging and tests.

TODO: move the stop height check to the syncer (#3442)

Methods from Deref<Target = ZebraDb>

pub fn is_empty(&self) -> bool

Returns true if the database is empty.

pub fn tip(&self) -> Option<(Height, Hash)>

Returns the tip height and hash, if there is one.

pub fn contains_height(&self, height: Height) -> bool

Returns true if height is present in the finalized state.

pub fn hash(&self, height: Height) -> Option<Hash>

Returns the finalized hash for a given block::Height if it is present.

pub fn contains_hash(&self, hash: Hash) -> bool

Returns true if hash is present in the finalized state.

pub fn height(&self, hash: Hash) -> Option<Height>

Returns the height of the given block if it exists.

pub fn prev_block_hash_for_hash(&self, hash: Hash) -> Option<Hash>

Returns the previous block hash for the given block hash in the finalized state.

pub fn prev_block_height_for_hash(&self, hash: Hash) -> Option<Height>

Returns the previous block height for the given block hash in the finalized state.

pub fn block_header(&self, hash_or_height: HashOrHeight) -> Option<Arc<Header>>

Returns the block::Header with block::Hash or Height, if it exists in the finalized chain.

pub fn block(&self, hash_or_height: HashOrHeight) -> Option<Arc<Block>>

Returns the Block with block::Hash or Height, if it exists in the finalized chain.

pub fn sapling_tree_by_hash_or_height( &self, hash_or_height: HashOrHeight, ) -> Option<Arc<NoteCommitmentTree>>

Returns the Sapling note commitment tree specified by a hash or height, if it exists in the finalized state.

pub fn orchard_tree_by_hash_or_height( &self, hash_or_height: HashOrHeight, ) -> Option<Arc<NoteCommitmentTree>>

Returns the Orchard note commitment tree specified by a hash or height, if it exists in the finalized state.

pub fn finalized_tip_hash(&self) -> Hash

Returns the hash of the current finalized tip block.

pub fn finalized_tip_height(&self) -> Option<Height>

Returns the height of the current finalized tip block.

pub fn tip_block(&self) -> Option<Arc<Block>>

Returns the tip block, if there is one.

pub fn transaction_location(&self, hash: Hash) -> Option<TransactionLocation>

Returns the TransactionLocation for transaction::Hash, if it exists in the finalized chain.

pub fn transaction_hash(&self, location: TransactionLocation) -> Option<Hash>

Returns the transaction::Hash for TransactionLocation, if it exists in the finalized chain.

pub fn transaction(&self, hash: Hash) -> Option<(Arc<Transaction>, Height)>

Returns the Transaction with transaction::Hash, and its Height, if a transaction with that hash exists in the finalized chain.

pub fn transaction_hashes_for_block( &self, hash_or_height: HashOrHeight, ) -> Option<Arc<[Hash]>>

Returns the transaction::Hashes in the block with hash_or_height, if it exists in this chain.

Hashes are returned in block order.

Returns None if the block is not found.

pub fn write_batch(&self, batch: DiskWriteBatch) -> Result<(), Error>

Writes the given batch to the database.

pub(crate) fn history_tree_cf( &self, ) -> TypedColumnFamily<'_, (), HistoryTreeParts>

Returns a typed handle to the history_tree column family.

pub(crate) fn legacy_history_tree_cf( &self, ) -> TypedColumnFamily<'_, Height, HistoryTreeParts>

Returns a legacy typed handle to the history_tree column family. This should not be used in new code.

pub(crate) fn raw_history_tree_cf( &self, ) -> TypedColumnFamily<'_, RawBytes, HistoryTreeParts>

Returns a generic raw key typed handle to the history_tree column family. This should not be used in new code.

pub(crate) fn chain_value_pools_cf( &self, ) -> TypedColumnFamily<'_, (), ValueBalance<NonNegative>>

Returns a typed handle to the chain value pools column family.

pub fn history_tree(&self) -> Arc<HistoryTree>

Returns the ZIP-221 history tree of the finalized tip.

If history trees have not been activated yet (pre-Heartwood), or the state is empty, returns an empty history tree.

pub(crate) fn history_trees_full_tip( &self, ) -> BTreeMap<RawBytes, Arc<HistoryTree>>

Returns all the history tip trees. We only store the history tree for the tip, so this method is only used in tests and upgrades.

pub fn finalized_value_pool(&self) -> ValueBalance<NonNegative>

Returns the stored ValueBalance for the best chain at the finalized tip height.

pub fn contains_sprout_nullifier(&self, sprout_nullifier: &Nullifier) -> bool

Returns true if the finalized state contains sprout_nullifier.

pub fn contains_sapling_nullifier(&self, sapling_nullifier: &Nullifier) -> bool

Returns true if the finalized state contains sapling_nullifier.

pub fn contains_orchard_nullifier(&self, orchard_nullifier: &Nullifier) -> bool

Returns true if the finalized state contains orchard_nullifier.

pub fn contains_sprout_anchor(&self, sprout_anchor: &Root) -> bool

Returns true if the finalized state contains sprout_anchor.

pub fn contains_sapling_anchor(&self, sapling_anchor: &Root) -> bool

Returns true if the finalized state contains sapling_anchor.

pub fn contains_orchard_anchor(&self, orchard_anchor: &Root) -> bool

Returns true if the finalized state contains orchard_anchor.

pub fn sprout_tree_for_tip(&self) -> Arc<NoteCommitmentTree>

Returns the Sprout note commitment tree of the finalized tip or the empty tree if the state is empty.

pub fn sprout_tree_by_anchor( &self, sprout_anchor: &Root, ) -> Option<Arc<NoteCommitmentTree>>

Returns the Sprout note commitment tree matching the given anchor.

This is used for interstitial tree building, which is unique to Sprout.

pub fn sprout_trees_full_map(&self) -> HashMap<Root, Arc<NoteCommitmentTree>>

Returns all the Sprout note commitment trees in the database.

Calling this method can load a lot of data into RAM, and delay block commit transactions.

pub fn sprout_trees_full_tip( &self, ) -> impl Iterator<Item = (RawBytes, Arc<NoteCommitmentTree>)> + '_

Returns all the Sprout note commitment tip trees. We only store the sprout tree for the tip, so this method is mainly used in tests.

pub fn sapling_tree_for_tip(&self) -> Arc<NoteCommitmentTree>

Returns the Sapling note commitment tree of the finalized tip or the empty tree if the state is empty.

pub fn sapling_tree_by_height( &self, height: &Height, ) -> Option<Arc<NoteCommitmentTree>>

Returns the Sapling note commitment tree matching the given block height, or None if the height is above the finalized tip.

pub fn sapling_tree_by_height_range<R>( &self, range: R, ) -> impl Iterator<Item = (Height, Arc<NoteCommitmentTree>)> + '_

where R: RangeBounds<Height>,

Returns the Sapling note commitment trees in the supplied range, in increasing height order.

pub fn sapling_tree_by_reversed_height_range<R>( &self, range: R, ) -> impl Iterator<Item = (Height, Arc<NoteCommitmentTree>)> + '_

where R: RangeBounds<Height>,

Returns the Sapling note commitment trees in the reversed range, in decreasing height order.

pub(in service::finalized_state) fn sapling_subtree_by_index( &self, index: impl Into<NoteCommitmentSubtreeIndex> + Copy, ) -> Option<NoteCommitmentSubtree<Node>>

Returns the Sapling note commitment subtree at this index.

Correctness

This method should not be used to get subtrees for RPC responses, because those subtree lists require that the start subtree is present in the list. Instead, use sapling_subtree_list_by_index_for_rpc().

pub fn sapling_subtree_list_by_index_range( &self, range: impl RangeBounds<NoteCommitmentSubtreeIndex>, ) -> BTreeMap<NoteCommitmentSubtreeIndex, NoteCommitmentSubtreeData<Node>>

Returns a list of Sapling NoteCommitmentSubtrees in the provided range.

fn sapling_subtree_for_tip(&self) -> Option<NoteCommitmentSubtree<Node>>

Get the sapling note commitment subtress for the finalized tip.

pub fn orchard_tree_for_tip(&self) -> Arc<NoteCommitmentTree>

Returns the Orchard note commitment tree of the finalized tip or the empty tree if the state is empty.

pub fn orchard_tree_by_height( &self, height: &Height, ) -> Option<Arc<NoteCommitmentTree>>

Returns the Orchard note commitment tree matching the given block height, or None if the height is above the finalized tip.

pub fn orchard_tree_by_height_range<R>( &self, range: R, ) -> impl Iterator<Item = (Height, Arc<NoteCommitmentTree>)> + '_

where R: RangeBounds<Height>,

Returns the Orchard note commitment trees in the supplied range, in increasing height order.

pub fn orchard_tree_by_reversed_height_range<R>( &self, range: R, ) -> impl Iterator<Item = (Height, Arc<NoteCommitmentTree>)> + '_

where R: RangeBounds<Height>,

Returns the Orchard note commitment trees in the reversed range, in decreasing height order.

pub(in service::finalized_state) fn orchard_subtree_by_index( &self, index: impl Into<NoteCommitmentSubtreeIndex> + Copy, ) -> Option<NoteCommitmentSubtree<Node>>

Returns the Orchard note commitment subtree at this index.

Correctness

This method should not be used to get subtrees for RPC responses, because those subtree lists require that the start subtree is present in the list. Instead, use orchard_subtree_list_by_index_for_rpc().

pub fn orchard_subtree_list_by_index_range( &self, range: impl RangeBounds<NoteCommitmentSubtreeIndex>, ) -> BTreeMap<NoteCommitmentSubtreeIndex, NoteCommitmentSubtreeData<Node>>

Returns a list of Orchard NoteCommitmentSubtrees in the provided range.

fn orchard_subtree_for_tip(&self) -> Option<NoteCommitmentSubtree<Node>>

Get the orchard note commitment subtress for the finalized tip.

pub fn note_commitment_trees_for_tip(&self) -> NoteCommitmentTrees

Returns the shielded note commitment trees of the finalized tip or the empty trees if the state is empty. Additionally, returns the sapling and orchard subtrees for the finalized tip if the current subtree is finalizing in the tip, None otherwise.

pub fn address_balance_location( &self, address: &Address, ) -> Option<AddressBalanceLocation>

Returns the AddressBalanceLocation for a transparent::Address, if it is in the finalized state.

pub fn address_balance(&self, address: &Address) -> Option<Amount<NonNegative>>

Returns the balance for a transparent::Address, if it is in the finalized state.

pub fn address_location(&self, address: &Address) -> Option<OutputLocation>

Returns the first output that sent funds to a transparent::Address, if it is in the finalized state.

This location is used as an efficient index key for addresses.

pub fn output_location(&self, outpoint: &OutPoint) -> Option<OutputLocation>

Returns the OutputLocation for a transparent::OutPoint.

This method returns the locations of spent and unspent outpoints. Returns None if the output was never in the finalized state.

pub fn utxo(&self, outpoint: &OutPoint) -> Option<OrderedUtxo>

Returns the transparent output for a transparent::OutPoint, if it is unspent in the finalized state.

pub fn utxo_by_location( &self, output_location: OutputLocation, ) -> Option<OrderedUtxo>

Returns the transparent output for an OutputLocation, if it is unspent in the finalized state.

pub fn address_utxos( &self, address: &Address, ) -> BTreeMap<OutputLocation, Output>

Returns the unspent transparent outputs for a transparent::Address, if they are in the finalized state.

pub fn address_utxo_locations( &self, address_location: OutputLocation, ) -> BTreeSet<AddressUnspentOutput>

Returns the unspent transparent output locations for a transparent::Address, if they are in the finalized state.

pub fn tx_id_by_location( &self, tx_location: TransactionLocation, ) -> Option<Hash>

Returns the transaction hash for an TransactionLocation.

pub fn address_tx_ids( &self, address: &Address, query_height_range: RangeInclusive<Height>, ) -> BTreeMap<TransactionLocation, Hash>

Returns the transaction IDs that sent or received funds to address, in the finalized chain query_height_range.

If address has no finalized sends or receives, or the query_height_range is totally outside the finalized block range, returns an empty list.

pub fn address_transaction_locations( &self, address_location: OutputLocation, query_height_range: RangeInclusive<Height>, ) -> BTreeSet<AddressTransaction>

Returns the locations of any transactions that sent or received from a transparent::Address, if they are in the finalized state.

pub fn partial_finalized_transparent_balance( &self, addresses: &HashSet<Address>, ) -> Amount<NonNegative>

Returns the total transparent balance for addresses in the finalized chain.

If none of the addresses has a balance, returns zero.

Correctness

Callers should apply the non-finalized balance change for addresses to the returned balance.

The total balance will only be correct if the non-finalized chain matches the finalized state. Specifically, the root of the partial non-finalized chain must be a child block of the finalized tip.

pub fn partial_finalized_address_utxos( &self, addresses: &HashSet<Address>, ) -> BTreeMap<OutputLocation, Output>

Returns the UTXOs for addresses in the finalized chain.

If none of the addresses has finalized UTXOs, returns an empty list.

Correctness

Callers should apply the non-finalized UTXO changes for addresses to the returned UTXOs.

The UTXOs will only be correct if the non-finalized chain matches or overlaps with the finalized state.

Specifically, a block in the partial chain must be a child block of the finalized tip. (But the child block does not have to be the partial chain root.)

pub fn partial_finalized_transparent_tx_ids( &self, addresses: &HashSet<Address>, query_height_range: RangeInclusive<Height>, ) -> BTreeMap<TransactionLocation, Hash>

Returns the transaction IDs that sent or received funds to addresses, in the finalized chain query_height_range.

If none of the addresses has finalized sends or receives, or the query_height_range is totally outside the finalized block range, returns an empty list.

Correctness

Callers should combine the non-finalized transactions for addresses with the returned transactions.

The transaction IDs will only be correct if the non-finalized chain matches or overlaps with the finalized state.

Specifically, a block in the partial chain must be a child block of the finalized tip. (But the child block does not have to be the partial chain root.)

This condition does not apply if there is only one address. Since address transactions are only appended by blocks, and this query reads them in order, it is impossible to get inconsistent transactions for a single address.

pub fn db(&self) -> &DiskDb

Returns the inner database.

This is a test-only and shielded-scan-only method, because it allows write access and raw read access to the RocksDB instance.

pub fn set_finalized_value_pool( &self, fake_value_pool: ValueBalance<NonNegative>, )

Allow to set up a fake value pool in the database for testing purposes.

pub fn populate_with_anchors(&self, block: &Block)

Artificially prime the note commitment tree anchor sets with anchors referenced in a block, for testing purposes only.

pub fn config(&self) -> &Config

Returns config for this database.

pub fn db_kind(&self) -> String

Returns the configured database kind for this database.

pub fn format_version_in_code(&self) -> Version

Returns the format version of the running code that created this ZebraDb instance in memory.

pub fn major_version(&self) -> u64

Returns the fixed major version for this database.

pub fn format_version_on_disk(&self) -> Result<Option<Version>, BoxError>

Returns the format version of this database on disk.

See database_format_version_on_disk() for details.

pub(crate) fn update_format_version_on_disk( &self, new_version: &Version, ) -> Result<(), BoxError>

Updates the format of this database on disk to the suppled version.

See write_database_format_version_to_disk() for details.

pub fn network(&self) -> Network

Returns the configured network for this database.

pub fn path(&self) -> &Path

Returns the Path where the files used by this database are located.

pub fn try_catch_up_with_primary(&self) -> Result<(), Error>

When called with a secondary DB instance, tries to catch up with the primary DB instance

pub(crate) fn check_max_on_disk_tip_height(&self) -> Result<(), String>

Check that the on-disk height is well below the maximum supported database height.

Zebra only supports on-disk heights up to 3 bytes.

Logs an Error

If Zebra is storing block heights that are close to MAX_ON_DISK_HEIGHT.

pub fn print_db_metrics(&self)

Logs metrics related to the underlying RocksDB instance.

This function prints various metrics and statistics about the RocksDB database, such as disk usage, memory usage, and other performance-related metrics.

Methods from Deref<Target = DiskDb>

pub fn list_cf(&self) -> Result<Vec<String>, Error>

Returns a list of column family names in this database.

const IDEAL_OPEN_FILE_LIMIT: u64 = 1_024u64

const MIN_OPEN_FILE_LIMIT: u64 = 512u64

const RESERVED_FILE_COUNT: u64 = 48u64

const MEMTABLE_RAM_CACHE_MEGABYTES: usize = 128usize

pub fn print_db_metrics(&self)

Prints rocksdb metrics for each column family along with total database disk size, live data disk size and database memory size.

pub fn try_catch_up_with_primary(&self) -> Result<(), Error>

When called with a secondary DB instance, tries to catch up with the primary DB instance

pub fn zs_forward_range_iter<C, K, V, R>( &self, cf: &C, range: R, ) -> impl Iterator<Item = (K, V)> + '_

where C: AsColumnFamilyRef, K: IntoDisk + FromDisk, V: FromDisk, R: RangeBounds<K>,

Returns a forward iterator over the items in cf in range.

Holding this iterator open might delay block commit transactions.

pub fn zs_reverse_range_iter<C, K, V, R>( &self, cf: &C, range: R, ) -> impl Iterator<Item = (K, V)> + '_

where C: AsColumnFamilyRef, K: IntoDisk + FromDisk, V: FromDisk, R: RangeBounds<K>,

Returns a reverse iterator over the items in cf in range.

Holding this iterator open might delay block commit transactions.

fn zs_range_iter_with_direction<C, K, V, R>( &self, cf: &C, range: R, reverse: bool, ) -> impl Iterator<Item = (K, V)> + '_

where C: AsColumnFamilyRef, K: IntoDisk + FromDisk, V: FromDisk, R: RangeBounds<K>,

Returns an iterator over the items in cf in range.

RocksDB iterators are ordered by increasing key bytes by default. Otherwise, if reverse is true, the iterator is ordered by decreasing key bytes.

Holding this iterator open might delay block commit transactions.

pub fn db_kind(&self) -> String

Returns the configured database kind for this database.

pub fn format_version_in_code(&self) -> Version

Returns the format version of the running code that created this DiskDb instance in memory.

pub fn major_version(&self) -> u64

Returns the fixed major version for this database.

pub fn network(&self) -> Network

Returns the configured network for this database.

pub fn path(&self) -> &Path

Returns the Path where the files used by this database are located.

fn inner(&self) -> &Arc<DBWithThreadMode<SingleThreaded>>

Returns the low-level rocksdb inner database.

pub fn cf_handle(&self, cf_name: &str) -> Option<ColumnFamilyRef<'_>>

Returns the column family handle for cf_name.

pub(crate) fn write(&self, batch: DiskWriteBatch) -> Result<(), Error>

Writes batch to the database.

pub(crate) fn shared_database_owners(&self) -> usize

Returns the number of shared instances of this database.

Concurrency

The actual number of owners can be higher or lower than the returned value, because databases can simultaneously be cloned or dropped in other threads.

However, if the number of owners is 1, and the caller has exclusive access, the count can’t increase unless that caller clones the database.

fn assert_default_cf_is_empty(&self)

Check that the “default” column family is empty.

Panics

If Zebra has a bug where it is storing data in the wrong column family.

Methods from Deref<Target = DBWithThreadMode<SingleThreaded>>

pub fn delete_range_cf_opt<K>( &self, cf: &impl AsColumnFamilyRef, from: K, to: K, writeopts: &WriteOptions, ) -> Result<(), Error>

where K: AsRef<[u8]>,

Removes the database entries in the range ["from", "to") using given write options.

pub fn delete_range_cf<K>( &self, cf: &impl AsColumnFamilyRef, from: K, to: K, ) -> Result<(), Error>

where K: AsRef<[u8]>,

Removes the database entries in the range ["from", "to") using default write options.

pub fn write_opt( &self, batch: WriteBatchWithTransaction<false>, writeopts: &WriteOptions, ) -> Result<(), Error>

pub fn write( &self, batch: WriteBatchWithTransaction<false>, ) -> Result<(), Error>

pub fn write_without_wal( &self, batch: WriteBatchWithTransaction<false>, ) -> Result<(), Error>

pub fn path(&self) -> &Path

pub fn flush_wal(&self, sync: bool) -> Result<(), Error>

Flushes the WAL buffer. If sync is set to true, also syncs the data to disk.

pub fn flush_opt(&self, flushopts: &FlushOptions) -> Result<(), Error>

Flushes database memtables to SST files on the disk.

pub fn flush(&self) -> Result<(), Error>

Flushes database memtables to SST files on the disk using default options.

pub fn flush_cf_opt( &self, cf: &impl AsColumnFamilyRef, flushopts: &FlushOptions, ) -> Result<(), Error>

Flushes database memtables to SST files on the disk for a given column family.

pub fn flush_cfs_opt( &self, cfs: &[&impl AsColumnFamilyRef], opts: &FlushOptions, ) -> Result<(), Error>

Flushes multiple column families.

If atomic flush is not enabled, it is equivalent to calling flush_cf multiple times. If atomic flush is enabled, it will flush all column families specified in cfs up to the latest sequence number at the time when flush is requested.

pub fn flush_cf(&self, cf: &impl AsColumnFamilyRef) -> Result<(), Error>

Flushes database memtables to SST files on the disk for a given column family using default options.

pub fn get_opt<K>( &self, key: K, readopts: &ReadOptions, ) -> Result<Option<Vec<u8>>, Error>

where K: AsRef<[u8]>,

Return the bytes associated with a key value with read options. If you only intend to use the vector returned temporarily, consider using get_pinned_opt to avoid unnecessary memory copy.

pub fn get<K>(&self, key: K) -> Result<Option<Vec<u8>>, Error>

where K: AsRef<[u8]>,

Return the bytes associated with a key value. If you only intend to use the vector returned temporarily, consider using get_pinned to avoid unnecessary memory copy.

pub fn get_cf_opt<K>( &self, cf: &impl AsColumnFamilyRef, key: K, readopts: &ReadOptions, ) -> Result<Option<Vec<u8>>, Error>

where K: AsRef<[u8]>,

Return the bytes associated with a key value and the given column family with read options. If you only intend to use the vector returned temporarily, consider using get_pinned_cf_opt to avoid unnecessary memory.

pub fn get_cf<K>( &self, cf: &impl AsColumnFamilyRef, key: K, ) -> Result<Option<Vec<u8>>, Error>

where K: AsRef<[u8]>,

Return the bytes associated with a key value and the given column family. If you only intend to use the vector returned temporarily, consider using get_pinned_cf to avoid unnecessary memory.

pub fn get_pinned_opt<K>( &self, key: K, readopts: &ReadOptions, ) -> Result<Option<DBPinnableSlice<'_>>, Error>

where K: AsRef<[u8]>,

Return the value associated with a key using RocksDB’s PinnableSlice so as to avoid unnecessary memory copy.

pub fn get_pinned<K>( &self, key: K, ) -> Result<Option<DBPinnableSlice<'_>>, Error>

where K: AsRef<[u8]>,

Return the value associated with a key using RocksDB’s PinnableSlice so as to avoid unnecessary memory copy. Similar to get_pinned_opt but leverages default options.

pub fn get_pinned_cf_opt<K>( &self, cf: &impl AsColumnFamilyRef, key: K, readopts: &ReadOptions, ) -> Result<Option<DBPinnableSlice<'_>>, Error>

where K: AsRef<[u8]>,

Return the value associated with a key using RocksDB’s PinnableSlice so as to avoid unnecessary memory copy. Similar to get_pinned_opt but allows specifying ColumnFamily

pub fn get_pinned_cf<K>( &self, cf: &impl AsColumnFamilyRef, key: K, ) -> Result<Option<DBPinnableSlice<'_>>, Error>

where K: AsRef<[u8]>,

Return the value associated with a key using RocksDB’s PinnableSlice so as to avoid unnecessary memory copy. Similar to get_pinned_cf_opt but leverages default options.

pub fn multi_get<K, I>(&self, keys: I) -> Vec<Result<Option<Vec<u8>>, Error>>

where K: AsRef<[u8]>, I: IntoIterator<Item = K>,

Return the values associated with the given keys.

pub fn multi_get_opt<K, I>( &self, keys: I, readopts: &ReadOptions, ) -> Vec<Result<Option<Vec<u8>>, Error>>

where K: AsRef<[u8]>, I: IntoIterator<Item = K>,

Return the values associated with the given keys using read options.

pub fn multi_get_cf<'a, 'b, K, I, W>( &'a self, keys: I, ) -> Vec<Result<Option<Vec<u8>>, Error>>

where 'b: 'a, K: AsRef<[u8]>, I: IntoIterator<Item = (&'b W, K)>, W: 'b + AsColumnFamilyRef,

Return the values associated with the given keys and column families.

pub fn multi_get_cf_opt<'a, 'b, K, I, W>( &'a self, keys: I, readopts: &ReadOptions, ) -> Vec<Result<Option<Vec<u8>>, Error>>

where 'b: 'a, K: AsRef<[u8]>, I: IntoIterator<Item = (&'b W, K)>, W: 'b + AsColumnFamilyRef,

Return the values associated with the given keys and column families using read options.

pub fn batched_multi_get_cf<'a, K, I>( &self, cf: &impl AsColumnFamilyRef, keys: I, sorted_input: bool, ) -> Vec<Result<Option<DBPinnableSlice<'_>>, Error>>

where K: AsRef<[u8]> + 'a + ?Sized, I: IntoIterator<Item = &'a K>,

Return the values associated with the given keys and the specified column family where internally the read requests are processed in batch if block-based table SST format is used. It is a more optimized version of multi_get_cf.

pub fn batched_multi_get_cf_opt<'a, K, I>( &self, cf: &impl AsColumnFamilyRef, keys: I, sorted_input: bool, readopts: &ReadOptions, ) -> Vec<Result<Option<DBPinnableSlice<'_>>, Error>>

where K: AsRef<[u8]> + 'a + ?Sized, I: IntoIterator<Item = &'a K>,

Return the values associated with the given keys and the specified column family where internally the read requests are processed in batch if block-based table SST format is used. It is a more optimized version of multi_get_cf_opt.

pub fn key_may_exist<K>(&self, key: K) -> bool

where K: AsRef<[u8]>,

Returns false if the given key definitely doesn’t exist in the database, otherwise returns true. This function uses default ReadOptions.

pub fn key_may_exist_opt<K>(&self, key: K, readopts: &ReadOptions) -> bool

where K: AsRef<[u8]>,

Returns false if the given key definitely doesn’t exist in the database, otherwise returns true.

pub fn key_may_exist_cf<K>(&self, cf: &impl AsColumnFamilyRef, key: K) -> bool

where K: AsRef<[u8]>,

Returns false if the given key definitely doesn’t exist in the specified column family, otherwise returns true. This function uses default ReadOptions.

pub fn key_may_exist_cf_opt<K>( &self, cf: &impl AsColumnFamilyRef, key: K, readopts: &ReadOptions, ) -> bool

where K: AsRef<[u8]>,

Returns false if the given key definitely doesn’t exist in the specified column family, otherwise returns true.

pub fn key_may_exist_cf_opt_value<K>( &self, cf: &impl AsColumnFamilyRef, key: K, readopts: &ReadOptions, ) -> (bool, Option<CSlice>)

where K: AsRef<[u8]>,

If the key definitely does not exist in the database, then this method returns (false, None), else (true, None) if it may. If the key is found in memory, then it returns (true, Some<CSlice>).

This check is potentially lighter-weight than calling get(). One way to make this lighter weight is to avoid doing any IOs.

pub fn iterator<'a, 'b>( &'a self, mode: IteratorMode<'_>, ) -> DBIteratorWithThreadMode<'b, DBCommon<T, D>>

where 'a: 'b,

pub fn iterator_opt<'a, 'b>( &'a self, mode: IteratorMode<'_>, readopts: ReadOptions, ) -> DBIteratorWithThreadMode<'b, DBCommon<T, D>>

where 'a: 'b,

pub fn iterator_cf_opt<'a, 'b>( &'a self, cf_handle: &impl AsColumnFamilyRef, readopts: ReadOptions, mode: IteratorMode<'_>, ) -> DBIteratorWithThreadMode<'b, DBCommon<T, D>>

where 'a: 'b,

Opens an iterator using the provided ReadOptions. This is used when you want to iterate over a specific ColumnFamily with a modified ReadOptions

pub fn full_iterator<'a, 'b>( &'a self, mode: IteratorMode<'_>, ) -> DBIteratorWithThreadMode<'b, DBCommon<T, D>>

where 'a: 'b,

Opens an iterator with set_total_order_seek enabled. This must be used to iterate across prefixes when set_memtable_factory has been called with a Hash-based implementation.

pub fn prefix_iterator<'a, 'b, P>( &'a self, prefix: P, ) -> DBIteratorWithThreadMode<'b, DBCommon<T, D>>

where 'a: 'b, P: AsRef<[u8]>,

pub fn iterator_cf<'a, 'b>( &'a self, cf_handle: &impl AsColumnFamilyRef, mode: IteratorMode<'_>, ) -> DBIteratorWithThreadMode<'b, DBCommon<T, D>>

where 'a: 'b,

pub fn full_iterator_cf<'a, 'b>( &'a self, cf_handle: &impl AsColumnFamilyRef, mode: IteratorMode<'_>, ) -> DBIteratorWithThreadMode<'b, DBCommon<T, D>>

where 'a: 'b,

pub fn prefix_iterator_cf<'a, P>( &'a self, cf_handle: &impl AsColumnFamilyRef, prefix: P, ) -> DBIteratorWithThreadMode<'a, DBCommon<T, D>>

where P: AsRef<[u8]>,

pub fn raw_iterator<'a, 'b>( &'a self, ) -> DBRawIteratorWithThreadMode<'b, DBCommon<T, D>>

where 'a: 'b,

Opens a raw iterator over the database, using the default read options

pub fn raw_iterator_cf<'a, 'b>( &'a self, cf_handle: &impl AsColumnFamilyRef, ) -> DBRawIteratorWithThreadMode<'b, DBCommon<T, D>>

where 'a: 'b,

Opens a raw iterator over the given column family, using the default read options

pub fn raw_iterator_opt<'a, 'b>( &'a self, readopts: ReadOptions, ) -> DBRawIteratorWithThreadMode<'b, DBCommon<T, D>>

where 'a: 'b,

Opens a raw iterator over the database, using the given read options

pub fn raw_iterator_cf_opt<'a, 'b>( &'a self, cf_handle: &impl AsColumnFamilyRef, readopts: ReadOptions, ) -> DBRawIteratorWithThreadMode<'b, DBCommon<T, D>>

where 'a: 'b,

Opens a raw iterator over the given column family, using the given read options

pub fn snapshot(&self) -> SnapshotWithThreadMode<'_, DBCommon<T, D>>

pub fn put_opt<K, V>( &self, key: K, value: V, writeopts: &WriteOptions, ) -> Result<(), Error>

where K: AsRef<[u8]>, V: AsRef<[u8]>,

pub fn put_cf_opt<K, V>( &self, cf: &impl AsColumnFamilyRef, key: K, value: V, writeopts: &WriteOptions, ) -> Result<(), Error>

where K: AsRef<[u8]>, V: AsRef<[u8]>,

pub fn merge_opt<K, V>( &self, key: K, value: V, writeopts: &WriteOptions, ) -> Result<(), Error>

where K: AsRef<[u8]>, V: AsRef<[u8]>,

pub fn merge_cf_opt<K, V>( &self, cf: &impl AsColumnFamilyRef, key: K, value: V, writeopts: &WriteOptions, ) -> Result<(), Error>

where K: AsRef<[u8]>, V: AsRef<[u8]>,

pub fn delete_opt<K>( &self, key: K, writeopts: &WriteOptions, ) -> Result<(), Error>

where K: AsRef<[u8]>,

pub fn delete_cf_opt<K>( &self, cf: &impl AsColumnFamilyRef, key: K, writeopts: &WriteOptions, ) -> Result<(), Error>

where K: AsRef<[u8]>,

pub fn put<K, V>(&self, key: K, value: V) -> Result<(), Error>

where K: AsRef<[u8]>, V: AsRef<[u8]>,

pub fn put_cf<K, V>( &self, cf: &impl AsColumnFamilyRef, key: K, value: V, ) -> Result<(), Error>

where K: AsRef<[u8]>, V: AsRef<[u8]>,

pub fn merge<K, V>(&self, key: K, value: V) -> Result<(), Error>

where K: AsRef<[u8]>, V: AsRef<[u8]>,

pub fn merge_cf<K, V>( &self, cf: &impl AsColumnFamilyRef, key: K, value: V, ) -> Result<(), Error>

where K: AsRef<[u8]>, V: AsRef<[u8]>,

pub fn delete<K>(&self, key: K) -> Result<(), Error>

where K: AsRef<[u8]>,

pub fn delete_cf<K>( &self, cf: &impl AsColumnFamilyRef, key: K, ) -> Result<(), Error>

where K: AsRef<[u8]>,

pub fn compact_range<S, E>(&self, start: Option<S>, end: Option<E>)

where S: AsRef<[u8]>, E: AsRef<[u8]>,

Runs a manual compaction on the Range of keys given. This is not likely to be needed for typical usage.

pub fn compact_range_opt<S, E>( &self, start: Option<S>, end: Option<E>, opts: &CompactOptions, )

where S: AsRef<[u8]>, E: AsRef<[u8]>,

Same as compact_range but with custom options.

pub fn compact_range_cf<S, E>( &self, cf: &impl AsColumnFamilyRef, start: Option<S>, end: Option<E>, )

where S: AsRef<[u8]>, E: AsRef<[u8]>,

Runs a manual compaction on the Range of keys given on the given column family. This is not likely to be needed for typical usage.

pub fn compact_range_cf_opt<S, E>( &self, cf: &impl AsColumnFamilyRef, start: Option<S>, end: Option<E>, opts: &CompactOptions, )

where S: AsRef<[u8]>, E: AsRef<[u8]>,

Same as compact_range_cf but with custom options.

pub fn wait_for_compact( &self, opts: &WaitForCompactOptions, ) -> Result<(), Error>

Wait for all flush and compactions jobs to finish. Jobs to wait include the unscheduled (queued, but not scheduled yet).

NOTE: This may also never return if there’s sufficient ongoing writes that keeps flush and compaction going without stopping. The user would have to cease all the writes to DB to make this eventually return in a stable state. The user may also use timeout option in WaitForCompactOptions to make this stop waiting and return when timeout expires.

pub fn set_options(&self, opts: &[(&str, &str)]) -> Result<(), Error>

pub fn set_options_cf( &self, cf: &impl AsColumnFamilyRef, opts: &[(&str, &str)], ) -> Result<(), Error>

pub fn property_value( &self, name: impl CStrLike, ) -> Result<Option<String>, Error>

Retrieves a RocksDB property by name.

Full list of properties could be find here.

pub fn property_value_cf( &self, cf: &impl AsColumnFamilyRef, name: impl CStrLike, ) -> Result<Option<String>, Error>

Retrieves a RocksDB property by name, for a specific column family.

Full list of properties could be find here.

pub fn property_int_value( &self, name: impl CStrLike, ) -> Result<Option<u64>, Error>

Retrieves a RocksDB property and casts it to an integer.

Full list of properties that return int values could be find here.

pub fn property_int_value_cf( &self, cf: &impl AsColumnFamilyRef, name: impl CStrLike, ) -> Result<Option<u64>, Error>

Retrieves a RocksDB property for a specific column family and casts it to an integer.

Full list of properties that return int values could be find here.

pub fn latest_sequence_number(&self) -> u64

The sequence number of the most recent transaction.

pub fn get_updates_since(&self, seq_number: u64) -> Result<DBWALIterator, Error>

Iterate over batches of write operations since a given sequence.

Produce an iterator that will provide the batches of write operations that have occurred since the given sequence (see latest_sequence_number()). Use the provided iterator to retrieve each (u64, WriteBatch) tuple, and then gather the individual puts and deletes using the WriteBatch::iterate() function.

Calling get_updates_since() with a sequence number that is out of bounds will return an error.

pub fn try_catch_up_with_primary(&self) -> Result<(), Error>

Tries to catch up with the primary by reading as much as possible from the log files.

pub fn ingest_external_file<P>(&self, paths: Vec<P>) -> Result<(), Error>

where P: AsRef<Path>,

Loads a list of external SST files created with SstFileWriter into the DB with default opts

pub fn ingest_external_file_opts<P>( &self, opts: &IngestExternalFileOptions, paths: Vec<P>, ) -> Result<(), Error>

where P: AsRef<Path>,

Loads a list of external SST files created with SstFileWriter into the DB

pub fn ingest_external_file_cf<P>( &self, cf: &impl AsColumnFamilyRef, paths: Vec<P>, ) -> Result<(), Error>

where P: AsRef<Path>,

Loads a list of external SST files created with SstFileWriter into the DB for given Column Family with default opts

pub fn ingest_external_file_cf_opts<P>( &self, cf: &impl AsColumnFamilyRef, opts: &IngestExternalFileOptions, paths: Vec<P>, ) -> Result<(), Error>

where P: AsRef<Path>,

Loads a list of external SST files created with SstFileWriter into the DB for given Column Family

pub fn get_column_family_metadata(&self) -> ColumnFamilyMetaData

Obtains the LSM-tree meta data of the default column family of the DB

pub fn get_column_family_metadata_cf( &self, cf: &impl AsColumnFamilyRef, ) -> ColumnFamilyMetaData

Obtains the LSM-tree meta data of the specified column family of the DB

pub fn live_files(&self) -> Result<Vec<LiveFile>, Error>

Returns a list of all table files with their level, start key and end key

pub fn delete_file_in_range<K>(&self, from: K, to: K) -> Result<(), Error>

where K: AsRef<[u8]>,

Delete sst files whose keys are entirely in the given range.

Could leave some keys in the range which are in files which are not entirely in the range.

Note: L0 files are left regardless of whether they’re in the range.

SnapshotWithThreadModes before the delete might not see the data in the given range.

pub fn delete_file_in_range_cf<K>( &self, cf: &impl AsColumnFamilyRef, from: K, to: K, ) -> Result<(), Error>

where K: AsRef<[u8]>,

Same as delete_file_in_range but only for specific column family

pub fn cancel_all_background_work(&self, wait: bool)

Request stopping background work, if wait is true wait until it’s done.

pub fn cf_handle(&self, name: &str) -> Option<&ColumnFamily>

Returns the underlying column family handle

pub fn create_cf<N>(&self, name: N, opts: &Options) -> Result<(), Error>

where N: AsRef<str>,

Creates column family with given name and options

pub fn drop_cf(&self, name: &str) -> Result<(), Error>

Drops the column family with the given name by internally locking the inner column family map. This avoids needing &mut self reference

pub fn cf_handle(&self, name: &str) -> Option<Arc<BoundColumnFamily<'_>>>

Returns the underlying column family handle

pub fn transaction( &self, ) -> Transaction<'_, DBCommon<T, OptimisticTransactionDBInner>>

Creates a transaction with default options.

pub fn transaction_opt( &self, writeopts: &WriteOptions, otxn_opts: &OptimisticTransactionOptions, ) -> Transaction<'_, DBCommon<T, OptimisticTransactionDBInner>>

Creates a transaction with default options.

pub fn write_opt( &self, batch: WriteBatchWithTransaction<true>, writeopts: &WriteOptions, ) -> Result<(), Error>

pub fn write(&self, batch: WriteBatchWithTransaction<true>) -> Result<(), Error>

pub fn write_without_wal( &self, batch: WriteBatchWithTransaction<true>, ) -> Result<(), Error>

Trait Implementations

impl Clone for FinalizedState

fn clone(&self) -> FinalizedState

Returns a copy of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for FinalizedState

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl Deref for FinalizedState

type Target = ZebraDb

The resulting type after dereferencing.

fn deref(&self) -> &Self::Target

Dereferences the value.