MDBX Database Compaction

Compacts an MDBX database file by copying it without garbage-collected pages, producing a smaller file.

The user provides a datadir path. The database being compacted is always <datadir>/chaindata/mdbx.dat.

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 database must not be in use. Always confirm this with the user before proceeding.
~2x free disk space relative to the current mdbx.dat size — the compacted copy is written alongside the original.

Procedure

1. Validate

Verify that <datadir>/chaindata/mdbx.dat exists. Abort if it does not.

2. Report Size and Check Disk Space

Run du -sh <datadir>/chaindata/mdbx.dat and report the size to the user.
Run df -h <datadir>/chaindata and check available space. If available space is less than the mdbx.dat size, abort and tell the user there is not enough disk space.

3. 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 in the output to estimate space savings.

4. Build `mdbx_copy`

make db-tools

This places mdbx_copy at ./build/bin/mdbx_copy.

5. Run Compaction

Create a sibling directory for the compacted output. The destination argument to mdbx_copy must be a file path, not a directory.

mkdir -p <datadir>/chaindata-compacted
./build/bin/mdbx_copy -c <datadir>/chaindata <datadir>/chaindata-compacted/mdbx.dat

Source is the directory <datadir>/chaindata
Destination is a file <datadir>/chaindata-compacted/mdbx.dat

This can take hours to days for large databases. Run in background.

6. Replace the Original

After mdbx_copy completes successfully:

Delete the old files:

rm <datadir>/chaindata/mdbx.dat <datadir>/chaindata/mdbx.lck

Move the compacted file in:

mv <datadir>/chaindata-compacted/mdbx.dat <datadir>/chaindata/mdbx.dat

Clean up:
```
rmdir <datadir>/chaindata-compacted
```

7. Verify

Run du -sh <datadir>/chaindata/mdbx.dat and report the new size compared to the original.

The user can now restart erigon.

Overall Score

81/100

Grade

B

Good

Grades are signals, not a certification. Always review a skill yourself before use.

Safety

78

Quality

85

Clarity

82

Completeness

78

Summary

This skill guides users through compacting an MDBX database file (mdbx.dat) in Erigon to reclaim disk space and resolve MDBX_MAP_FULL errors. It provides a procedural workflow covering prerequisites validation, disk space checking, optional diagnostics, and safe file replacement with explicit warnings about service shutdown and disk space requirements.

Detected Capabilities

file readshell executionfile deletionfile movedisk space validation

Trigger Keywords

Phrases that agents use to match this skill to user intent.

compact mdbx databasereclaim mdbx spaceshrink mdbx.datmdbx_copy compactionresolve map fullerigon database maintenance

Risk Signals

WARNING

File deletion pattern: rm <datadir>/chaindata/mdbx.dat

Section 6, Step 1

WARNING

Destructive operation (rm) performed on user-provided path without confirmation checkpoint

Section 6, Step 1

INFO

mv command moves file to replace original database

Section 6, Step 2

Use Cases

Shrink mdbx.dat when reclaimable space is high
Resolve MDBX_MAP_FULL errors by compacting the database
Free up disk space on Erigon nodes
Diagnose database fragmentation before committing to compaction
Safely replace the original database after compaction completes

Quality Notes

Clear prerequisites emphasizing service shutdown and disk space requirements
Well-structured step-by-step procedure with clear input/output for each phase
Explicit warnings about 2x disk space requirement and service state
Optional diagnostic step (mdbx_stat) helps users assess value before committing
Procedure correctly scopes operations to specific datadir path and chaindata subdirectory
Good use of example commands with source/destination clarification
Potential improvement: add explicit confirmation checkpoint before destructive operations in step 6
Good practice: separates output to sibling directory before replacing original

Model: claude-haiku-4-5-20251001Analyzed: Aug 20, 2026

Reviews

Add this skill to your library to leave a review.

No reviews yet

Be the first to share your experience.

erigon-mdbx-compact