etch
Untersuchen und warten Sie einen Etch-Store – Convex' inhaltsadressierte Datenbank. Verwenden Sie dies, wenn Sie Peer-Speicher untersuchen, Korruption diagnostizieren, Garbage Collection durchführen oder…
npx skills add https://github.com/convex-dev/convex --skill etchEtch Store Operations
Etch is Convex's content-addressed store: values are keyed by hash, and a single root hash reaches everything retained. Peers keep their state here.
Every subcommand takes the store file with -e / --etch:
java -jar convex.jar etch info -e /path/to/store.etch
Inspecting
| Command | Purpose |
|---|---|
etch info | Summary of the database — start here |
etch validate | Check store integrity; -m/--max-failures N to bound reporting |
etch dump | Export contents, CSV by default (value ID, type, memory size, encoding) |
etch read <hash>... | Read specific values by hash; --limit N to cap output |
info, dump and read take -o / --output-file to write to a file rather
than the terminal — use it for dump on any real store, which is large.
Start a diagnosis with info, then validate. If validation reports failures,
capture the output before doing anything that mutates the store.
Maintenance
These modify or destroy data. Confirm with the user, and make sure the peer using the store is stopped first — operating on a live store risks corruption.
| Command | Effect |
|---|---|
etch gc | Garbage collect: retains the root and everything reachable, discards the rest. In-place by default; -o/--output <file> collects into a fresh file instead |
etch clear | Clears the root data. Does not collect garbage |
etch migrate --into <dest> | Copy everything into another store; --set-root to set the destination root |
etch repair --into <dest> | Reconstruct a fresh store from independently validated cells; source unchanged |
etch recover | Adopt a completed GC cutover and roll forward — for a store interrupted mid-GC |
etch write -c/--cvx <source> | Write a CVM value into the store |
To compact safely, prefer gc -o <new-file>: it collects into a fresh file and
leaves the source unmodified (note: status levels above PERSISTED, e.g.
ANNOUNCED, survive an in-place GC but not --output). Use migrate to copy
into another (possibly non-empty) store, or to change the store's format
version or encryption — see below.
repair is the offline salvage path for a dirty or damaged source. It holds an
exclusive source lock, scans through physical EOF, and writes only canonical
CAD3 values whose stored content hashes verify. A complete result requires both
a fully persisted selected root and an exhaustive scan. If either condition
fails, the command reports failure but may leave a valid partial destination;
never replace the source with that output automatically.
Recovering an interrupted GC is what recover is for — reach for it before
concluding a store is lost.
Encrypted Stores (Etch v3)
Etch format v3 supports encrypted stores — format spec in
convex-core/docs/ETCHv3.md.
Opening an encrypted store: any etch subcommand takes --etch-key <alias>
(keystore key alias or public-key prefix, password via --etch-keypass) or
--etch-key-file <file> (raw or hex 32-byte master key; - reads stdin).
With neither, the v3 header's public-key hint selects a keystore key
automatically, or an interactive session prompts for a hex key.
Converting a store: etch migrate (and gc -o) accept destination
options — --into-version (1, 2 or 3), --into-cipher (none,
aes-256-ctr or chacha20), --into-key / --into-key-file /
--into-keypass for the destination key, --into-encrypt-index (negatable)
and --into-public-key-hint. Encryption options require version 3; without a
destination key the resolved source key is reused.