From 55a49080c6af0c3880ebe3935aafb9fff5a52526 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Andr=C3=A9s=20David=20Ram=C3=ADrez=20Chiquillo?= Date: Wed, 12 Nov 2025 08:21:56 -0500 Subject: [PATCH] feat(db): introduce --db.page-size argument (#19594) --- crates/node/core/src/args/database.rs | 48 +++++++++++++++++++ .../storage/db/src/implementation/mdbx/mod.rs | 9 ++++ docs/vocs/docs/pages/cli/reth/db.mdx | 9 ++++ docs/vocs/docs/pages/cli/reth/db/diff.mdx | 9 ++++ docs/vocs/docs/pages/cli/reth/download.mdx | 9 ++++ docs/vocs/docs/pages/cli/reth/export-era.mdx | 9 ++++ docs/vocs/docs/pages/cli/reth/import-era.mdx | 9 ++++ docs/vocs/docs/pages/cli/reth/import.mdx | 9 ++++ docs/vocs/docs/pages/cli/reth/init-state.mdx | 9 ++++ docs/vocs/docs/pages/cli/reth/init.mdx | 9 ++++ docs/vocs/docs/pages/cli/reth/node.mdx | 9 ++++ docs/vocs/docs/pages/cli/reth/prune.mdx | 9 ++++ docs/vocs/docs/pages/cli/reth/re-execute.mdx | 9 ++++ docs/vocs/docs/pages/cli/reth/stage/drop.mdx | 9 ++++ docs/vocs/docs/pages/cli/reth/stage/dump.mdx | 9 ++++ docs/vocs/docs/pages/cli/reth/stage/run.mdx | 9 ++++ .../vocs/docs/pages/cli/reth/stage/unwind.mdx | 9 ++++ 17 files changed, 192 insertions(+) diff --git a/crates/node/core/src/args/database.rs b/crates/node/core/src/args/database.rs index 6384f36a80..298669e198 100644 --- a/crates/node/core/src/args/database.rs +++ b/crates/node/core/src/args/database.rs @@ -33,6 +33,18 @@ pub struct DatabaseArgs { /// The default value is 8TB. #[arg(long = "db.max-size", value_parser = parse_byte_size)] pub max_size: Option, + /// Database page size (e.g., 4KB, 8KB, 16KB). + /// + /// Specifies the page size used by the MDBX database. + /// + /// The page size determines the maximum database size. + /// MDBX supports up to 2^31 pages, so with the default 4KB page size, the maximum + /// database size is 8TB. To allow larger databases, increase this value to 8KB or higher. + /// + /// WARNING: This setting is only configurable at database creation; changing + /// it later requires re-syncing. + #[arg(long = "db.page-size", value_parser = parse_byte_size)] + pub page_size: Option, /// Database growth step (e.g., 4GB, 4KB) #[arg(long = "db.growth-step", value_parser = parse_byte_size)] pub growth_step: Option, @@ -73,6 +85,7 @@ impl DatabaseArgs { .with_exclusive(self.exclusive) .with_max_read_transaction_duration(max_read_transaction_duration) .with_geometry_max_size(self.max_size) + .with_geometry_page_size(self.page_size) .with_growth_step(self.growth_step) .with_max_readers(self.max_readers) .with_sync_mode(self.sync_mode) @@ -305,6 +318,41 @@ mod tests { assert!(result.is_err()); } + #[test] + fn test_command_parser_with_valid_page_size_from_str() { + let cmd = CommandParser::::try_parse_from(["reth", "--db.page-size", "8KB"]) + .unwrap(); + assert_eq!(cmd.args.page_size, Some(KILOBYTE * 8)); + + let cmd = CommandParser::::try_parse_from(["reth", "--db.page-size", "1MB"]) + .unwrap(); + assert_eq!(cmd.args.page_size, Some(MEGABYTE)); + + // Test with spaces + let cmd = + CommandParser::::try_parse_from(["reth", "--db.page-size", "16 KB"]) + .unwrap(); + assert_eq!(cmd.args.page_size, Some(KILOBYTE * 16)); + + // Test with just a number (bytes) + let cmd = CommandParser::::try_parse_from(["reth", "--db.page-size", "4096"]) + .unwrap(); + assert_eq!(cmd.args.page_size, Some(KILOBYTE * 4)); + } + + #[test] + fn test_command_parser_with_invalid_page_size() { + // Invalid text + let result = + CommandParser::::try_parse_from(["reth", "--db.page-size", "invalid"]); + assert!(result.is_err()); + + // Invalid unit + let result = + CommandParser::::try_parse_from(["reth", "--db.page-size", "7 ZB"]); + assert!(result.is_err()); + } + #[test] fn test_possible_values() { // Initialize the LogLevelValueParser diff --git a/crates/storage/db/src/implementation/mdbx/mod.rs b/crates/storage/db/src/implementation/mdbx/mod.rs index b00bfd3c9a..05da99d682 100644 --- a/crates/storage/db/src/implementation/mdbx/mod.rs +++ b/crates/storage/db/src/implementation/mdbx/mod.rs @@ -154,6 +154,15 @@ impl DatabaseArguments { self } + /// Sets the database page size value. + pub const fn with_geometry_page_size(mut self, page_size: Option) -> Self { + if let Some(size) = page_size { + self.geometry.page_size = Some(reth_libmdbx::PageSize::Set(size)); + } + + self + } + /// Sets the database sync mode. pub const fn with_sync_mode(mut self, sync_mode: Option) -> Self { if let Some(sync_mode) = sync_mode { diff --git a/docs/vocs/docs/pages/cli/reth/db.mdx b/docs/vocs/docs/pages/cli/reth/db.mdx index 6b98c08112..95e4bb20ca 100644 --- a/docs/vocs/docs/pages/cli/reth/db.mdx +++ b/docs/vocs/docs/pages/cli/reth/db.mdx @@ -78,6 +78,15 @@ Database: The default value is 8TB. + --db.page-size + Database page size (e.g., 4KB, 8KB, 16KB). + + Specifies the page size used by the MDBX database. + + The page size determines the maximum database size. MDBX supports up to 2^31 pages, so with the default 4KB page size, the maximum database size is 8TB. To allow larger databases, increase this value to 8KB or higher. + + WARNING: This setting is only configurable at database creation; changing it later requires re-syncing. + --db.growth-step Database growth step (e.g., 4GB, 4KB) diff --git a/docs/vocs/docs/pages/cli/reth/db/diff.mdx b/docs/vocs/docs/pages/cli/reth/db/diff.mdx index 5625853118..6032a93b20 100644 --- a/docs/vocs/docs/pages/cli/reth/db/diff.mdx +++ b/docs/vocs/docs/pages/cli/reth/db/diff.mdx @@ -41,6 +41,15 @@ Database: The default value is 8TB. + --db.page-size + Database page size (e.g., 4KB, 8KB, 16KB). + + Specifies the page size used by the MDBX database. + + The page size determines the maximum database size. MDBX supports up to 2^31 pages, so with the default 4KB page size, the maximum database size is 8TB. To allow larger databases, increase this value to 8KB or higher. + + WARNING: This setting is only configurable at database creation; changing it later requires re-syncing. + --db.growth-step Database growth step (e.g., 4GB, 4KB) diff --git a/docs/vocs/docs/pages/cli/reth/download.mdx b/docs/vocs/docs/pages/cli/reth/download.mdx index 0ba6c7407e..f13aeb0bc9 100644 --- a/docs/vocs/docs/pages/cli/reth/download.mdx +++ b/docs/vocs/docs/pages/cli/reth/download.mdx @@ -65,6 +65,15 @@ Database: The default value is 8TB. + --db.page-size + Database page size (e.g., 4KB, 8KB, 16KB). + + Specifies the page size used by the MDBX database. + + The page size determines the maximum database size. MDBX supports up to 2^31 pages, so with the default 4KB page size, the maximum database size is 8TB. To allow larger databases, increase this value to 8KB or higher. + + WARNING: This setting is only configurable at database creation; changing it later requires re-syncing. + --db.growth-step Database growth step (e.g., 4GB, 4KB) diff --git a/docs/vocs/docs/pages/cli/reth/export-era.mdx b/docs/vocs/docs/pages/cli/reth/export-era.mdx index 051c81fcce..16ea002972 100644 --- a/docs/vocs/docs/pages/cli/reth/export-era.mdx +++ b/docs/vocs/docs/pages/cli/reth/export-era.mdx @@ -65,6 +65,15 @@ Database: The default value is 8TB. + --db.page-size + Database page size (e.g., 4KB, 8KB, 16KB). + + Specifies the page size used by the MDBX database. + + The page size determines the maximum database size. MDBX supports up to 2^31 pages, so with the default 4KB page size, the maximum database size is 8TB. To allow larger databases, increase this value to 8KB or higher. + + WARNING: This setting is only configurable at database creation; changing it later requires re-syncing. + --db.growth-step Database growth step (e.g., 4GB, 4KB) diff --git a/docs/vocs/docs/pages/cli/reth/import-era.mdx b/docs/vocs/docs/pages/cli/reth/import-era.mdx index 14aa47e0ef..1eaa32a6fb 100644 --- a/docs/vocs/docs/pages/cli/reth/import-era.mdx +++ b/docs/vocs/docs/pages/cli/reth/import-era.mdx @@ -65,6 +65,15 @@ Database: The default value is 8TB. + --db.page-size + Database page size (e.g., 4KB, 8KB, 16KB). + + Specifies the page size used by the MDBX database. + + The page size determines the maximum database size. MDBX supports up to 2^31 pages, so with the default 4KB page size, the maximum database size is 8TB. To allow larger databases, increase this value to 8KB or higher. + + WARNING: This setting is only configurable at database creation; changing it later requires re-syncing. + --db.growth-step Database growth step (e.g., 4GB, 4KB) diff --git a/docs/vocs/docs/pages/cli/reth/import.mdx b/docs/vocs/docs/pages/cli/reth/import.mdx index b8051d9d2f..cc7ccc988c 100644 --- a/docs/vocs/docs/pages/cli/reth/import.mdx +++ b/docs/vocs/docs/pages/cli/reth/import.mdx @@ -65,6 +65,15 @@ Database: The default value is 8TB. + --db.page-size + Database page size (e.g., 4KB, 8KB, 16KB). + + Specifies the page size used by the MDBX database. + + The page size determines the maximum database size. MDBX supports up to 2^31 pages, so with the default 4KB page size, the maximum database size is 8TB. To allow larger databases, increase this value to 8KB or higher. + + WARNING: This setting is only configurable at database creation; changing it later requires re-syncing. + --db.growth-step Database growth step (e.g., 4GB, 4KB) diff --git a/docs/vocs/docs/pages/cli/reth/init-state.mdx b/docs/vocs/docs/pages/cli/reth/init-state.mdx index e43c87f806..4a00e88f1a 100644 --- a/docs/vocs/docs/pages/cli/reth/init-state.mdx +++ b/docs/vocs/docs/pages/cli/reth/init-state.mdx @@ -65,6 +65,15 @@ Database: The default value is 8TB. + --db.page-size + Database page size (e.g., 4KB, 8KB, 16KB). + + Specifies the page size used by the MDBX database. + + The page size determines the maximum database size. MDBX supports up to 2^31 pages, so with the default 4KB page size, the maximum database size is 8TB. To allow larger databases, increase this value to 8KB or higher. + + WARNING: This setting is only configurable at database creation; changing it later requires re-syncing. + --db.growth-step Database growth step (e.g., 4GB, 4KB) diff --git a/docs/vocs/docs/pages/cli/reth/init.mdx b/docs/vocs/docs/pages/cli/reth/init.mdx index 6ad439c6a0..c1cd24be23 100644 --- a/docs/vocs/docs/pages/cli/reth/init.mdx +++ b/docs/vocs/docs/pages/cli/reth/init.mdx @@ -65,6 +65,15 @@ Database: The default value is 8TB. + --db.page-size + Database page size (e.g., 4KB, 8KB, 16KB). + + Specifies the page size used by the MDBX database. + + The page size determines the maximum database size. MDBX supports up to 2^31 pages, so with the default 4KB page size, the maximum database size is 8TB. To allow larger databases, increase this value to 8KB or higher. + + WARNING: This setting is only configurable at database creation; changing it later requires re-syncing. + --db.growth-step Database growth step (e.g., 4GB, 4KB) diff --git a/docs/vocs/docs/pages/cli/reth/node.mdx b/docs/vocs/docs/pages/cli/reth/node.mdx index c0bd56cdfa..499ff1854d 100644 --- a/docs/vocs/docs/pages/cli/reth/node.mdx +++ b/docs/vocs/docs/pages/cli/reth/node.mdx @@ -750,6 +750,15 @@ Database: The default value is 8TB. + --db.page-size + Database page size (e.g., 4KB, 8KB, 16KB). + + Specifies the page size used by the MDBX database. + + The page size determines the maximum database size. MDBX supports up to 2^31 pages, so with the default 4KB page size, the maximum database size is 8TB. To allow larger databases, increase this value to 8KB or higher. + + WARNING: This setting is only configurable at database creation; changing it later requires re-syncing. + --db.growth-step Database growth step (e.g., 4GB, 4KB) diff --git a/docs/vocs/docs/pages/cli/reth/prune.mdx b/docs/vocs/docs/pages/cli/reth/prune.mdx index 1febf6cdd5..a24f297c6c 100644 --- a/docs/vocs/docs/pages/cli/reth/prune.mdx +++ b/docs/vocs/docs/pages/cli/reth/prune.mdx @@ -65,6 +65,15 @@ Database: The default value is 8TB. + --db.page-size + Database page size (e.g., 4KB, 8KB, 16KB). + + Specifies the page size used by the MDBX database. + + The page size determines the maximum database size. MDBX supports up to 2^31 pages, so with the default 4KB page size, the maximum database size is 8TB. To allow larger databases, increase this value to 8KB or higher. + + WARNING: This setting is only configurable at database creation; changing it later requires re-syncing. + --db.growth-step Database growth step (e.g., 4GB, 4KB) diff --git a/docs/vocs/docs/pages/cli/reth/re-execute.mdx b/docs/vocs/docs/pages/cli/reth/re-execute.mdx index 742cbe5482..cce93bf9b6 100644 --- a/docs/vocs/docs/pages/cli/reth/re-execute.mdx +++ b/docs/vocs/docs/pages/cli/reth/re-execute.mdx @@ -65,6 +65,15 @@ Database: The default value is 8TB. + --db.page-size + Database page size (e.g., 4KB, 8KB, 16KB). + + Specifies the page size used by the MDBX database. + + The page size determines the maximum database size. MDBX supports up to 2^31 pages, so with the default 4KB page size, the maximum database size is 8TB. To allow larger databases, increase this value to 8KB or higher. + + WARNING: This setting is only configurable at database creation; changing it later requires re-syncing. + --db.growth-step Database growth step (e.g., 4GB, 4KB) diff --git a/docs/vocs/docs/pages/cli/reth/stage/drop.mdx b/docs/vocs/docs/pages/cli/reth/stage/drop.mdx index 05153f3fc2..4a26cc909e 100644 --- a/docs/vocs/docs/pages/cli/reth/stage/drop.mdx +++ b/docs/vocs/docs/pages/cli/reth/stage/drop.mdx @@ -65,6 +65,15 @@ Database: The default value is 8TB. + --db.page-size + Database page size (e.g., 4KB, 8KB, 16KB). + + Specifies the page size used by the MDBX database. + + The page size determines the maximum database size. MDBX supports up to 2^31 pages, so with the default 4KB page size, the maximum database size is 8TB. To allow larger databases, increase this value to 8KB or higher. + + WARNING: This setting is only configurable at database creation; changing it later requires re-syncing. + --db.growth-step Database growth step (e.g., 4GB, 4KB) diff --git a/docs/vocs/docs/pages/cli/reth/stage/dump.mdx b/docs/vocs/docs/pages/cli/reth/stage/dump.mdx index b74ee2280b..874bb8d628 100644 --- a/docs/vocs/docs/pages/cli/reth/stage/dump.mdx +++ b/docs/vocs/docs/pages/cli/reth/stage/dump.mdx @@ -72,6 +72,15 @@ Database: The default value is 8TB. + --db.page-size + Database page size (e.g., 4KB, 8KB, 16KB). + + Specifies the page size used by the MDBX database. + + The page size determines the maximum database size. MDBX supports up to 2^31 pages, so with the default 4KB page size, the maximum database size is 8TB. To allow larger databases, increase this value to 8KB or higher. + + WARNING: This setting is only configurable at database creation; changing it later requires re-syncing. + --db.growth-step Database growth step (e.g., 4GB, 4KB) diff --git a/docs/vocs/docs/pages/cli/reth/stage/run.mdx b/docs/vocs/docs/pages/cli/reth/stage/run.mdx index a0314b73ba..dfaecd33f2 100644 --- a/docs/vocs/docs/pages/cli/reth/stage/run.mdx +++ b/docs/vocs/docs/pages/cli/reth/stage/run.mdx @@ -65,6 +65,15 @@ Database: The default value is 8TB. + --db.page-size + Database page size (e.g., 4KB, 8KB, 16KB). + + Specifies the page size used by the MDBX database. + + The page size determines the maximum database size. MDBX supports up to 2^31 pages, so with the default 4KB page size, the maximum database size is 8TB. To allow larger databases, increase this value to 8KB or higher. + + WARNING: This setting is only configurable at database creation; changing it later requires re-syncing. + --db.growth-step Database growth step (e.g., 4GB, 4KB) diff --git a/docs/vocs/docs/pages/cli/reth/stage/unwind.mdx b/docs/vocs/docs/pages/cli/reth/stage/unwind.mdx index 5c3a7d54f4..7d8359d5dc 100644 --- a/docs/vocs/docs/pages/cli/reth/stage/unwind.mdx +++ b/docs/vocs/docs/pages/cli/reth/stage/unwind.mdx @@ -70,6 +70,15 @@ Database: The default value is 8TB. + --db.page-size + Database page size (e.g., 4KB, 8KB, 16KB). + + Specifies the page size used by the MDBX database. + + The page size determines the maximum database size. MDBX supports up to 2^31 pages, so with the default 4KB page size, the maximum database size is 8TB. To allow larger databases, increase this value to 8KB or higher. + + WARNING: This setting is only configurable at database creation; changing it later requires re-syncing. + --db.growth-step Database growth step (e.g., 4GB, 4KB)