xone db is the command family for an xOneRS datadir: its MDBX database (chain.mdbx), its history segments and its checkpoints. It has 15 subcommands, and preimages has two of its own. Ten operations only read and can run beside a running node; the others write, and the node must be stopped first. This post lists them by job, from the command tree in bin/xone/src/flags.rs. Most came in pull requests merged on 2026-11-14 and 2026-11-15, so check xone db --help on your build; v0.1.0 has fewer.
For where the data lives, see how xOne stores XDC chain data.
Which commands are safe on a running node?
| Command | Shows | Source |
|---|---|---|
xone db stats |
Entries, pages and bytes per table, and the sizes of the segment, journal and checkpoint directories | flags.rs |
xone db usage |
All disk use of the node in one report, apparent and allocated, with any extra paths you name | flags.rs |
xone db inspect --table T [--prefix 0x..] [--limit n] |
Rows of one table as hex key and value | #1073 |
xone db get --table T --key 0x.. |
One value; exit 1 if the key is missing | #1073 |
xone db changes --address A [--slot S] [--from N] [--to M] |
One JSON line per block that changed an account or a slot, with before and after values (the archive history index, else the retained changesets) | #966 |
xone db inspect-trie [--top N] |
Account-trie nodes and bytes per depth, and the contracts with the largest storage tries | #967 |
xone db orphans [--code] |
Storage rows whose account is missing, and with --code bytecode no account names |
#977 |
xone db scrub |
Decodes every stored account and checks key and value lengths; prints damaged rows and exits 1 | #1111 |
xone db diff --left A --right B |
Row differences between two datadirs, one JSON line each; refuses a different schema or genesis | #934 |
xone db preimages export --out F |
Every address and slot preimage, each checked against its hash | #968 |
orphans, scrub and diff copy one page at a time, so their memory stays bounded on a large datadir. They still read the whole table, which takes disk time.
Which commands need the node stopped?
| Command | Does | Guard |
|---|---|---|
xone db unwind --to N |
Rolls the chain head back to block N, with the same unwind a peer reorg uses | Refuses below the committed block or above the head; takes the datadir lock (#1060) |
xone db prune |
Deletes bodies, receipts and their logs below the --history.* windows |
Cannot cut into the consensus lookback (#1100) |
xone db compact [--keep-old] |
Rewrites chain.mdbx without free pages and replaces it in place |
Takes the datadir lock (#1073) |
xone db compact-history |
Rewrites closed history segments below the committed floor as zstd-compressed files | Node must not run |
xone db preimages import --in F |
Adds preimages from a file; refuses a damaged or truncated file | |
xone db stage-run --stage S --from N --to M --copy D |
Copies the datadir and runs one sync stage over a range on the copy | Refuses the original, a live lock or a signer safety record (#1110) |
stage-run never writes to the original, so it is the way to reproduce a sync bug on a production datadir.
Back up the datadir before unwind, prune or compact: each one changes it in place. See upgrade and rollback.
What should I run after a crash or a disk problem?
xone db statsandxone db usage: is the database where you expect, and how big.xone db scrub: are the stored accounts and slots decodable. It can run while the node is up.xone db orphans --code: are there rows that point nowhere.- If the head is on a bad block: stop the node and
xone db unwind --to <last good block>.
If scrub reports damaged rows, there is no repair command; restore from a backup or a verified snapshot. See snapshot import with --staging.
How do I compare two nodes' databases?
Today, put both datadirs (or copies) on one host and run xone db diff. There is no per-table checksum that each host can compute on its own; we filed that as issue #1151.
How does this compare with other clients?
| Job | reth (as listed in reth db) | xOneRS |
|---|---|---|
| Table statistics | reth db stats |
xone db stats, xone db usage |
| Read rows or one key | reth db list, reth db get |
xone db inspect, xone db get |
| Compare two databases | reth db diff |
xone db diff |
| Content checksum of a table | reth db checksum |
none yet (#1151) |
| Delete table contents | reth db clear, reth db drop |
none; use prune, unwind or a fresh datadir |
Frequently asked questions
Which xone db commands can I run while the node is running?
stats, usage, inspect, get, changes, inspect-trie, orphans, scrub, diff and preimages export. They only read.
How do I roll back an xOne node without resyncing?
Stop it and run xone db unwind --datadir <dir> --to <block>. It refuses a block below the committed one.
How do I shrink chain.mdbx after pruning?
Stop the node and run xone db compact. It rewrites the file without free pages; --keep-old keeps the previous copy.
How do I check the stored state for corruption?
xone db scrub. It decodes every stored account and slot and exits 1 if a row is damaged.
Sources
This article describes the source and evidence at its review date. Check the linked repository for current implementation and qualification status.
Explore the engineering evidenceEdit this page on GitHub opens the Markdown source (content/blog/xone-db-toolkit/index.md). GitHub may ask you to sign in. Report a correction opens a prefilled GitHub issue for this page.