etcdutl

Offline utility for etcd data files. Source: etcdutl/.

Purpose

etcdutl is the offline counterpart to etcdctl. It never connects to a running cluster. Instead, it operates on the on-disk artifacts a member produces: snapshot DBs, WAL files, and (in some cases) the live member/ directory of a stopped node. Use it for:

• Verifying the integrity of a backup before relying on it.
• Restoring a snapshot into a fresh member directory.
• Migrating a bolt DB across schema versions.
• Computing or comparing hashes of stored data.

Directory layout

etcdutl/
├── main.go              # calls Start (defined in ctl.go)
├── ctl.go               # cobra root command
├── etcdutl/             # subcommand implementations
│   ├── snapshot_command.go
│   ├── backup_command.go
│   ├── defrag_command.go
│   ├── hashkv_command.go
│   ├── migrate_command.go
│   └── ...
└── snapshot/            # programmatic snapshot save/restore API

Key subcommands

Command	What it does
snapshot status <db>	Print revision/total-keys/hash for a snapshot DB
snapshot restore <db>	Materialize a snapshot into a new <name>.etcd member dir
snapshot save <db>	Pull a snapshot from a running cluster (mirrors etcdctl snapshot save)
backup	Legacy v2 → v3 backup conversion
defrag --data-dir <dir>	Defragment a stopped member's bbolt file in place
hashkv --data-dir <dir>	Hash the MVCC keyspace of a stopped member
migrate --data-dir <dir>	Apply schema migrations across versions (server/storage/schema/migration.go)
version	Print the embedded version stamp

The full reference lives in etcdutl/README.md.

Why a separate binary?

Operators routinely need to inspect or repair etcd data without bringing the cluster up. Splitting these tools into etcdutl keeps etcdctl's import graph free of server-side packages (storage, schema, mvcc) — the boundary is enforced by etcdctl/.gomodguard.yaml and etcdutl/.gomodguard.yaml.

How it works

etcdutl directly imports server packages — particularly server/storage/backend, server/storage/mvcc, server/storage/schema, and server/storage/wal — to read and rewrite on-disk state. The recent commit history at wiki time even includes a fix for missing Close() calls in etcdutl (PR #21686, 9c4b2d273), illustrating the intimacy of this coupling.

Integration points

• Imports server/storage/* for direct bolt + WAL access.
• Exports etcdutl/snapshot so etcdctl snapshot save can reuse the same code path.
• Imports pkg/cobrautl for the standard CLI shell.

Entry points for modification

• New subcommand → etcdutl/etcdutl/<verb>_command.go, register it in etcdutl/ctl.go.
• Snapshot logic shared with etcdctl → etcdutl/snapshot/ (be aware both binaries link this code).
• Schema migrations → server/storage/schema/migration.go plus a wiring update in etcdutl/etcdutl/migrate_command.go.

Related

• systems/wal — the WAL format etcdutl understands.
• systems/backend — the bbolt layout it edits.
• systems/schema — version + migration metadata.