reth_db_api/
lib.rs

Help
1//! reth's database abstraction layer.
2//!
3//! The database abstraction assumes that the underlying store is a KV store subdivided into tables.
4//!
5//! One or more changes are tied to a transaction that is atomically committed to the data store at
6//! the same time. Strong consistency in what data is written and when is important for reth, so it
7//! is not possible to write data to the database outside of using a transaction.
8//!
9//! Good starting points for this crate are:
10//!
11//! - [`Database`] for the main database abstraction
12//! - [`DbTx`] (RO) and [`DbTxMut`] (RW) for the transaction abstractions.
13//! - [`DbCursorRO`] (RO) and [`DbCursorRW`] (RW) for the cursor abstractions (see below).
14//!
15//! # Cursors and Walkers
16//!
17//! The abstraction also defines a couple of helpful abstractions for iterating and writing data:
18//!
19//! - **Cursors** ([`DbCursorRO`] / [`DbCursorRW`]) for iterating data in a table. Cursors are
20//!   assumed to resolve data in a sorted manner when iterating from start to finish, and it is safe
21//!   to assume that they are efficient at doing so.
22//! - **Walkers** ([`Walker`] / [`RangeWalker`] / [`ReverseWalker`]) use cursors to walk the entries
23//!   in a table, either fully from a specific point, or over a range.
24//!
25//! Dup tables (see below) also have corresponding cursors and walkers (e.g. [`DbDupCursorRO`]).
26//! These **should** be preferred when working with dup tables, as they provide additional methods
27//! that are optimized for dup tables.
28//!
29//! # Tables
30//!
31//! reth has two types of tables: simple KV stores (one key, one value) and dup tables (one key,
32//! many values). Dup tables can be efficient for certain types of data.
33//!
34//! Keys are de/serialized using the [`Encode`] and [`Decode`] traits, and values are de/serialized
35//! ("compressed") using the [`Compress`] and [`Decompress`] traits.
36//!
37//! Tables implement the [`Table`] trait.
38//!
39//! [`Database`]: crate::database::Database
40//! [`DbTx`]: crate::transaction::DbTx
41//! [`DbTxMut`]: crate::transaction::DbTxMut
42//! [`DbCursorRO`]: crate::cursor::DbCursorRO
43//! [`DbCursorRW`]: crate::cursor::DbCursorRW
44//! [`Walker`]: crate::cursor::Walker
45//! [`RangeWalker`]: crate::cursor::RangeWalker
46//! [`ReverseWalker`]: crate::cursor::ReverseWalker
47//! [`DbDupCursorRO`]: crate::cursor::DbDupCursorRO
48//! [`Encode`]: crate::table::Encode
49//! [`Decode`]: crate::table::Decode
50//! [`Compress`]: crate::table::Compress
51//! [`Decompress`]: crate::table::Decompress
52//! [`Table`]: crate::table::Table
53
54#![doc(
55    html_logo_url = "https://raw.githubusercontent.com/paradigmxyz/reth/main/assets/reth-docs.png",
56    html_favicon_url = "https://avatars0.githubusercontent.com/u/97369466?s=256",
57    issue_tracker_base_url = "https://github.com/paradigmxyz/reth/issues/"
58)]
59#![cfg_attr(not(test), warn(unused_crate_dependencies))]
60#![cfg_attr(docsrs, feature(doc_cfg, doc_auto_cfg))]
61
62/// Common types used throughout the abstraction.
63pub mod common;
64
65/// Cursor database traits.
66pub mod cursor;
67
68/// Database traits.
69pub mod database;
70
71/// Database metrics trait extensions.
72pub mod database_metrics;
73
74pub mod mock;
75
76/// Table traits
77pub mod table;
78
79pub mod tables;
80pub use tables::*;
81
82/// Transaction database traits.
83pub mod transaction;
84
85/// Re-exports
86pub use reth_storage_errors::db::{DatabaseError, DatabaseWriteOperation};
87
88pub mod models;
89mod scale;
90
91mod utils;
92
93pub use database::Database;
94
95mod unwind;
96pub use unwind::DbTxUnwindExt;
reth_db_api/lib.rs

reth_db_api/
lib.rs
