reth_db/
lib.rs

1//! MDBX implementation for reth's database abstraction layer.
2//!
3//! This crate is an implementation of `reth-db-api` for MDBX, as well as a few other common
4//! database types.
5//!
6//! # Overview
7//!
8//! An overview of the current data model of reth can be found in the [`mod@tables`] module.
9
10#![doc(
11    html_logo_url = "https://raw.githubusercontent.com/paradigmxyz/reth/main/assets/reth-docs.png",
12    html_favicon_url = "https://avatars0.githubusercontent.com/u/97369466?s=256",
13    issue_tracker_base_url = "https://github.com/paradigmxyz/reth/issues/"
14)]
15#![cfg_attr(not(test), warn(unused_crate_dependencies))]
16#![cfg_attr(docsrs, feature(doc_cfg))]
17
18mod implementation;
19pub mod lockfile;
20#[cfg(feature = "mdbx")]
21mod metrics;
22pub mod static_file;
23#[cfg(feature = "mdbx")]
24mod utils;
25pub mod version;
26
27#[cfg(feature = "mdbx")]
28pub mod mdbx;
29
30pub use reth_storage_errors::db::{DatabaseError, DatabaseWriteOperation};
31#[cfg(feature = "mdbx")]
32pub use utils::is_database_empty;
33
34#[cfg(feature = "mdbx")]
35pub use mdbx::{create_db, init_db, open_db, open_db_read_only, DatabaseEnv, DatabaseEnvKind};
36
37pub use models::ClientVersion;
38pub use reth_db_api::*;
39
40/// Collection of database test utilities
41#[cfg(any(test, feature = "test-utils"))]
42pub mod test_utils {
43    use super::*;
44    use crate::mdbx::DatabaseArguments;
45    use parking_lot::RwLock;
46    use reth_db_api::{database::Database, database_metrics::DatabaseMetrics};
47    use reth_fs_util;
48    use std::{
49        fmt::Formatter,
50        path::{Path, PathBuf},
51        sync::Arc,
52    };
53    use tempfile::TempDir;
54
55    /// Error during database open
56    pub const ERROR_DB_OPEN: &str = "could not open the database file";
57    /// Error during database creation
58    pub const ERROR_DB_CREATION: &str = "could not create the database file";
59    /// Error during database creation
60    pub const ERROR_STATIC_FILES_CREATION: &str = "could not create the static file path";
61    /// Error during table creation
62    pub const ERROR_TABLE_CREATION: &str = "could not create tables in the database";
63    /// Error during tempdir creation
64    pub const ERROR_TEMPDIR: &str = "could not create a temporary directory";
65
66    /// A database will delete the db dir when dropped.
67    pub struct TempDatabase<DB> {
68        db: Option<DB>,
69        path: PathBuf,
70        /// Executed right before a database transaction is created.
71        pre_tx_hook: RwLock<Box<dyn Fn() + Send + Sync>>,
72        /// Executed right after a database transaction is created.
73        post_tx_hook: RwLock<Box<dyn Fn() + Send + Sync>>,
74    }
75
76    impl<DB: std::fmt::Debug> std::fmt::Debug for TempDatabase<DB> {
77        fn fmt(&self, f: &mut Formatter<'_>) -> std::fmt::Result {
78            f.debug_struct("TempDatabase").field("db", &self.db).field("path", &self.path).finish()
79        }
80    }
81
82    impl<DB> Drop for TempDatabase<DB> {
83        fn drop(&mut self) {
84            if let Some(db) = self.db.take() {
85                drop(db);
86                let _ = reth_fs_util::remove_dir_all(&self.path);
87            }
88        }
89    }
90
91    impl<DB> TempDatabase<DB> {
92        /// Create new [`TempDatabase`] instance.
93        pub fn new(db: DB, path: PathBuf) -> Self {
94            Self {
95                db: Some(db),
96                path,
97                pre_tx_hook: RwLock::new(Box::new(|| ())),
98                post_tx_hook: RwLock::new(Box::new(|| ())),
99            }
100        }
101
102        /// Returns the reference to inner db.
103        pub const fn db(&self) -> &DB {
104            self.db.as_ref().unwrap()
105        }
106
107        /// Returns the path to the database.
108        pub fn path(&self) -> &Path {
109            &self.path
110        }
111
112        /// Convert temp database into inner.
113        pub fn into_inner_db(mut self) -> DB {
114            self.db.take().unwrap() // take out db to avoid clean path in drop fn
115        }
116
117        /// Sets [`TempDatabase`] new pre transaction creation hook.
118        pub fn set_pre_transaction_hook(&self, hook: Box<dyn Fn() + Send + Sync>) {
119            let mut db_hook = self.pre_tx_hook.write();
120            *db_hook = hook;
121        }
122
123        /// Sets [`TempDatabase`] new post transaction creation hook.
124        pub fn set_post_transaction_hook(&self, hook: Box<dyn Fn() + Send + Sync>) {
125            let mut db_hook = self.post_tx_hook.write();
126            *db_hook = hook;
127        }
128    }
129
130    impl<DB: Database> Database for TempDatabase<DB> {
131        type TX = <DB as Database>::TX;
132        type TXMut = <DB as Database>::TXMut;
133        fn tx(&self) -> Result<Self::TX, DatabaseError> {
134            self.pre_tx_hook.read()();
135            let tx = self.db().tx()?;
136            self.post_tx_hook.read()();
137            Ok(tx)
138        }
139
140        fn tx_mut(&self) -> Result<Self::TXMut, DatabaseError> {
141            self.db().tx_mut()
142        }
143
144        fn path(&self) -> std::path::PathBuf {
145            self.db().path()
146        }
147    }
148
149    impl<DB: DatabaseMetrics> DatabaseMetrics for TempDatabase<DB> {
150        fn report_metrics(&self) {
151            self.db().report_metrics()
152        }
153    }
154
155    /// Create `static_files` path for testing
156    #[track_caller]
157    pub fn create_test_static_files_dir() -> (TempDir, PathBuf) {
158        let temp_dir = TempDir::with_prefix("reth-test-static-").expect(ERROR_TEMPDIR);
159        let path = temp_dir.path().to_path_buf();
160        (temp_dir, path)
161    }
162
163    /// Create `rocksdb` path for testing
164    #[track_caller]
165    pub fn create_test_rocksdb_dir() -> (TempDir, PathBuf) {
166        let temp_dir = TempDir::with_prefix("reth-test-rocksdb-").expect(ERROR_TEMPDIR);
167        let path = temp_dir.path().to_path_buf();
168        (temp_dir, path)
169    }
170
171    /// Get a temporary directory path to use for the database
172    pub fn tempdir_path() -> PathBuf {
173        let builder = tempfile::Builder::new().prefix("reth-test-").rand_bytes(8).tempdir();
174        builder.expect(ERROR_TEMPDIR).keep()
175    }
176
177    /// Create read/write database for testing
178    #[track_caller]
179    pub fn create_test_rw_db() -> Arc<TempDatabase<DatabaseEnv>> {
180        let path = tempdir_path();
181        let emsg = format!("{ERROR_DB_CREATION}: {path:?}");
182
183        let db = init_db(&path, DatabaseArguments::test()).expect(&emsg);
184
185        Arc::new(TempDatabase::new(db, path))
186    }
187
188    /// Create read/write database for testing
189    #[track_caller]
190    pub fn create_test_rw_db_with_path<P: AsRef<Path>>(path: P) -> Arc<TempDatabase<DatabaseEnv>> {
191        let path = path.as_ref().to_path_buf();
192        let emsg = format!("{ERROR_DB_CREATION}: {path:?}");
193        let db = init_db(path.as_path(), DatabaseArguments::test()).expect(&emsg);
194        Arc::new(TempDatabase::new(db, path))
195    }
196
197    /// Create read/write database for testing within a data directory.
198    ///
199    /// The database is created at `datadir/db`, and `TempDatabase` will clean up the entire
200    /// `datadir` on drop.
201    #[track_caller]
202    pub fn create_test_rw_db_with_datadir<P: AsRef<Path>>(
203        datadir: P,
204    ) -> Arc<TempDatabase<DatabaseEnv>> {
205        let datadir = datadir.as_ref().to_path_buf();
206        let db_path = datadir.join("db");
207        let emsg = format!("{ERROR_DB_CREATION}: {db_path:?}");
208        let db = init_db(&db_path, DatabaseArguments::test()).expect(&emsg);
209        Arc::new(TempDatabase::new(db, datadir))
210    }
211
212    /// Create read only database for testing
213    #[track_caller]
214    pub fn create_test_ro_db() -> Arc<TempDatabase<DatabaseEnv>> {
215        let args = DatabaseArguments::test();
216
217        let path = tempdir_path();
218        let emsg = format!("{ERROR_DB_CREATION}: {path:?}");
219        {
220            init_db(path.as_path(), args.clone()).expect(&emsg);
221        }
222        let db = open_db_read_only(path.as_path(), args).expect(ERROR_DB_OPEN);
223        Arc::new(TempDatabase::new(db, path))
224    }
225}
226
227#[cfg(test)]
228mod tests {
229    use crate::{
230        init_db,
231        mdbx::DatabaseArguments,
232        open_db, tables,
233        version::{db_version_file_path, DatabaseVersionError},
234    };
235    use assert_matches::assert_matches;
236    use reth_db_api::{
237        cursor::DbCursorRO, database::Database, models::ClientVersion, transaction::DbTx,
238    };
239    use reth_libmdbx::MaxReadTransactionDuration;
240    use std::time::Duration;
241    use tempfile::tempdir;
242
243    #[test]
244    fn test_temp_database_cleanup() {
245        // Test that TempDatabase properly cleans up its directory when dropped
246        let temp_path = {
247            let db = crate::test_utils::create_test_rw_db();
248            let path = db.path();
249            assert!(path.exists(), "Database directory should exist while TempDatabase is alive");
250            path
251            // TempDatabase dropped here
252        };
253
254        // Verify the directory was cleaned up
255        assert!(
256            !temp_path.exists(),
257            "Database directory should be cleaned up after TempDatabase is dropped"
258        );
259    }
260
261    #[test]
262    fn db_version() {
263        let path = tempdir().unwrap();
264
265        let args = DatabaseArguments::new(ClientVersion::default())
266            .with_max_read_transaction_duration(Some(MaxReadTransactionDuration::Unbounded));
267
268        // Database is empty
269        {
270            let db = init_db(&path, args.clone());
271            assert_matches!(db, Ok(_));
272        }
273
274        // Database is not empty, current version is the same as in the file
275        {
276            let db = init_db(&path, args.clone());
277            assert_matches!(db, Ok(_));
278        }
279
280        // Database is not empty, version file is malformed
281        {
282            reth_fs_util::write(path.path().join(db_version_file_path(&path)), "invalid-version")
283                .unwrap();
284            let db = init_db(&path, args.clone());
285            assert!(db.is_err());
286            assert_matches!(
287                db.unwrap_err().downcast_ref::<DatabaseVersionError>(),
288                Some(DatabaseVersionError::MalformedFile)
289            )
290        }
291
292        // Database is not empty, version file contains not matching version
293        {
294            reth_fs_util::write(path.path().join(db_version_file_path(&path)), "0").unwrap();
295            let db = init_db(&path, args);
296            assert!(db.is_err());
297            assert_matches!(
298                db.unwrap_err().downcast_ref::<DatabaseVersionError>(),
299                Some(DatabaseVersionError::VersionMismatch { version: 0 })
300            )
301        }
302    }
303
304    #[test]
305    fn db_client_version() {
306        let path = tempdir().unwrap();
307
308        // Empty client version is not recorded
309        {
310            let db = init_db(&path, DatabaseArguments::new(ClientVersion::default())).unwrap();
311            let tx = db.tx().unwrap();
312            let mut cursor = tx.cursor_read::<tables::VersionHistory>().unwrap();
313            assert_matches!(cursor.first(), Ok(None));
314        }
315
316        // Client version is recorded
317        let first_version = ClientVersion { version: String::from("v1"), ..Default::default() };
318        {
319            let db = init_db(&path, DatabaseArguments::new(first_version.clone())).unwrap();
320            let tx = db.tx().unwrap();
321            let mut cursor = tx.cursor_read::<tables::VersionHistory>().unwrap();
322            assert_eq!(
323                cursor
324                    .walk_range(..)
325                    .unwrap()
326                    .map(|x| x.map(|(_, v)| v))
327                    .collect::<Result<Vec<_>, _>>()
328                    .unwrap(),
329                vec![first_version.clone()]
330            );
331        }
332
333        // Same client version is not duplicated.
334        {
335            let db = init_db(&path, DatabaseArguments::new(first_version.clone())).unwrap();
336            let tx = db.tx().unwrap();
337            let mut cursor = tx.cursor_read::<tables::VersionHistory>().unwrap();
338            assert_eq!(
339                cursor
340                    .walk_range(..)
341                    .unwrap()
342                    .map(|x| x.map(|(_, v)| v))
343                    .collect::<Result<Vec<_>, _>>()
344                    .unwrap(),
345                vec![first_version.clone()]
346            );
347        }
348
349        // Different client version is recorded
350        std::thread::sleep(Duration::from_secs(1));
351        let second_version = ClientVersion { version: String::from("v2"), ..Default::default() };
352        {
353            let db = init_db(&path, DatabaseArguments::new(second_version.clone())).unwrap();
354            let tx = db.tx().unwrap();
355            let mut cursor = tx.cursor_read::<tables::VersionHistory>().unwrap();
356            assert_eq!(
357                cursor
358                    .walk_range(..)
359                    .unwrap()
360                    .map(|x| x.map(|(_, v)| v))
361                    .collect::<Result<Vec<_>, _>>()
362                    .unwrap(),
363                vec![first_version.clone(), second_version.clone()]
364            );
365        }
366
367        // Different client version is recorded on db open.
368        std::thread::sleep(Duration::from_secs(1));
369        let third_version = ClientVersion { version: String::from("v3"), ..Default::default() };
370        {
371            let db = open_db(path.path(), DatabaseArguments::new(third_version.clone())).unwrap();
372            let tx = db.tx().unwrap();
373            let mut cursor = tx.cursor_read::<tables::VersionHistory>().unwrap();
374            assert_eq!(
375                cursor
376                    .walk_range(..)
377                    .unwrap()
378                    .map(|x| x.map(|(_, v)| v))
379                    .collect::<Result<Vec<_>, _>>()
380                    .unwrap(),
381                vec![first_version, second_version, third_version]
382            );
383        }
384    }
385}
reth_db/lib.rs

reth_db/
lib.rs
