Struct zebra_state::ZebraDb

pub struct ZebraDb {
    config: Arc<Config>,
    debug_skip_format_upgrades: bool,
    format_change_handle: Option<DbFormatChangeThreadHandle>,
    db: DiskDb,
}

Wrapper struct to ensure high-level zebra-state database access goes through the correct API.

rocksdb allows concurrent writes through a shared reference, so database instances are cloneable. When the final clone is dropped, the database is closed.

Fields

config: Arc<Config>

The configuration for the database.

debug_skip_format_upgrades: bool

Should format upgrades and format checks be skipped for this instance? Only used in test code.

format_change_handle: Option<DbFormatChangeThreadHandle>

A handle to a running format change task, which cancels the task when dropped.

Concurrency

This field should be dropped before the database field, so the format upgrade task is cancelled before the database is dropped. This helps avoid some kinds of deadlocks.

db: DiskDb

The inner low-level database wrapper for the RocksDB database.

Implementations

impl 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(in service::finalized_state) fn write_block( &mut self, finalized: FinalizedBlock, prev_note_commitment_trees: Option<NoteCommitmentTrees>, network: &Network, source: &str, ) -> Result<Hash, BoxError>

Write finalized to the finalized state.

Uses:

• history_tree: the current tip’s history tree
• network: the configured network
• source: 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

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

Writes the given batch to the database.

impl ZebraDb

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.

impl ZebraDb

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.

impl ZebraDb

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.

impl ZebraDb

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.

impl ZebraDb

pub fn new( config: &Config, db_kind: impl AsRef<str>, format_version_in_code: &Version, network: &Network, debug_skip_format_upgrades: bool, column_families_in_code: impl IntoIterator<Item = String>, read_only: bool, ) -> ZebraDb

Opens or creates the database at a path based on the kind, major version and network, with the supplied column families, preserving any existing column families, and returns a shared high-level typed database wrapper.

If debug_skip_format_upgrades is true, don’t do any format upgrades or format checks. This argument is only used when running tests, it is ignored in production code.

pub fn spawn_format_change(&mut self, format_change: DbFormatChange)

Launch any required format changes or format checks, and store their thread handle.

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 check_for_panics(&mut self)

Check for panics in code running in spawned threads. If a thread exited with a panic, resume that panic.

This method should be called regularly, so that panics are detected as soon as possible.

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 shutdown(&mut self, force: bool)

Shut down the database, cleaning up background tasks and ephemeral data.

If force is true, clean up regardless of any shared references. force can cause errors accessing the database from other shared references. It should only be used in debugging or test code, immediately before a manual shutdown.

See DiskDb::shutdown for details.

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.

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.

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 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 ZebraDb

fn clone(&self) -> ZebraDb

Returns a copy of the value.

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

Performs copy-assignment from source.

impl Debug for ZebraDb

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

Formats the value using the given formatter.

impl Drop for ZebraDb

fn drop(&mut self)

Executes the destructor for this type.

impl Deref for ZebraDb

type Target = DiskDb

The resulting type after dereferencing.

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

Dereferences the value.