| name | erigon-mdbx-compact |
| user-invocable | false |
| description | Compact an existing MDBX database instance to reclaim free/reclaimable space. Use this when the user wants to shrink mdbx.dat, reclaim MDBX garbage-collected pages, or fix MDBX_MAP_FULL issues. |
| allowed-tools | Bash, Read, Glob |
MDBX Database Compaction
erigon db compact rewrites every mdbx database of a datadir without its free
pages, producing smaller files. MDBX reuses free pages instead of returning them
to the filesystem, so mdbx.dat never shrinks on its own.
The user provides a datadir path. The command finds every database under it
(chaindata, txpool, downloader, migrations, nodes/*, caplin/*, ...),
not only chaindata.
When to Use
mdbx_stat -ef shows a high "Reclaimable" percentage- The database hit
MDBX_MAP_FULL
- The user wants to shrink the on-disk size of
mdbx.dat
Prerequisites
- Erigon and rpcdaemon must be stopped. The command takes the datadir lock
and opens each database exclusively, so it fails cleanly rather than
corrupting a database in use. Still confirm with the user first.
- Free space for a second copy of each database, on the volume that database
already lives on. The copy is written to a
<db>/compacting/ subdirectory,
then moved back over the original.
Procedure
1. Report Size and Check Disk Space
- Run
du -sh <datadir>/chaindata/mdbx.dat and report the size to the user.
- Check free space per database, not once for the datadir: a database may sit
on its own volume through a symlink or mount, and its copy is staged next to
it. Run
find <datadir> -name mdbx.dat -not -path '*/compacting/*' -print0 | while IFS= read -r -d '' f; do du -sh "$f"; df -h "$(dirname "$f")" | tail -1; done
and compare each database against the free space on its own volume. If any
has less free space than its own mdbx.dat, abort and tell the user.
2. Diagnose (Optional)
If the user wants to see whether compaction is worthwhile before proceeding:
make db-tools
./build/bin/mdbx_stat -ef <datadir>/chaindata
Look at the Reclaimable line to estimate the space savings.
3. Run Compaction
make erigon
./build/bin/erigon db compact --datadir=<datadir>
This can take hours for large databases. Run in background.
Each database logs [compact] compacting with its label, then
[compact] compacted with the before/after sizes. Mode and owner of the
original file are preserved, and the stale mdbx.lck is removed.
4. Verify
Run du -sh <datadir>/chaindata/mdbx.dat and report the new size compared to
the original.
The user can now restart erigon.
Notes
- A crashed run can leave a
<db>/compacting/ directory behind. The next run
deletes it, so no cleanup is needed.
- To change
--db.pagesize you need a copy, not a compaction: the destination
keeps whatever page size it was created with, and mdbx_to_mdbx passes a
targetPageSize of 0, so it inherits the source's. Pre-create the new db with
ONLY_CREATE_DB=true erigon --datadir=<new> --chain=<chain> --db.pagesize=8kb,
then integration mdbx_to_mdbx --datadir=<old> --chaindata=<old>/chaindata --chaindata.to=<new>/chaindata.
Both --chaindata flags name a database directory, not a datadir root, and
--datadir is required even though the copy does not read it — the full
recipe is in cmd/integration/Readme.md.
