Storine v0.3.0

Tools

Command-line tool

storage-cli checks health, scrapes metrics, takes and restores backups, changes cluster membership and follows change feeds.

storage-cli <command> [args...]
storage-cli --help
storage-cli --version

Remote commands#

Remote commands talk to a running server. They take an address as host:port with an IP address, not a host name.

Environment variableMeaning
STORAGE_TOKENToken to authenticate with
STORAGE_TLS_CAPEM certificates to trust. Turns TLS on
STORAGE_TLS_SERVER_NAMEThe name to expect in the server's certificate. Default: its address
CommandRoleDoes
remote-health <addr>readPrint the node's health report as JSON
remote-metrics <addr>readPrint metrics in Prometheus text format. Standalone and single-group nodes
remote-checkpoint <addr>adminCheckpoint now
remote-compact <addr>adminCompact arena segments now
remote-backup <addr> <name>adminTake an online backup into STORAGE_BACKUP_ROOT/<name> on the server. On a range cluster, a cluster-wide backup
remote-restore <addr> <name>adminRestore a cluster backup into an empty range cluster
changefeed <addr> <out.jsonl> <cursor-file> [options]adminFollow a range cluster's changes into a JSON-lines file
cluster <addr> [members]readMembers, their roles, the leader, the term and the commit index
cluster <addr> add <id> <host:port>adminAdd a voter. It joins as a learner and is promoted once caught up
cluster <addr> add-learner <id> <host:port>adminAdd a non-voting learner
cluster <addr> promote <id>adminPromote a caught-up learner to voter
cluster <addr> remove <id>adminRemove a member, the leader included

Membership changes can be sent to any member: a follower's redirect to the leader is followed. See clusters.

export STORAGE_TOKEN=ops-token-0123456789abcdef
storage-cli remote-health 10.0.0.1:7878
storage-cli cluster 10.0.0.1:7878 members
storage-cli remote-backup 10.0.0.1:7878 nightly-2026-11-16

Change feeds#

storage-cli changefeed <addr> <out.jsonl> <cursor-file> [--collection C] [--from wall.logical] [--once] [--interval-ms N]
OptionMeaning
--collection COnly this collection's changes
--from wall.logicalStart at this timestamp instead of the cursor file's
--onceRead what is there, then exit
--interval-ms NHow often to poll for more

Each change is one JSON line, appended to the output file. The feed is at-least-once: after a restart it resumes from the cursor file, and a change may repeat. Range clusters only. More in range clusters.

Point-in-time recovery#

storage-cli restore-pitr <backup> <restore-dir> <time> [--archive DIR]... [--wal FILE]...

Restores a backup as it was at <time> (RFC 3339, or nanoseconds since the epoch) into a new directory, replaying archived WAL (--archive, a server's STORAGE_WAL_ARCHIVE/documents) and WAL files (--wal). It runs offline, without a server. The steps are in backups and recovery.

Local commands#

These open a data directory directly, with the server stopped:

CommandDoes
stats <db_dir>Engine and memory-mapping statistics
verify <db_dir>Check every record's checksums and relationships
compact <db_dir> [min_ratio]Compact fragmented arena segments
snapshot <db_dir> <dest_dir>Copy a consistent snapshot
backup <db_dir> <backup_dir>An online backup with the WAL position it covers
archive-wal <db_dir> <backup_dir>Archive the WAL into a backup, for point-in-time recovery
inspect-header <rec_file>Print and verify a record file's 64-byte header
get <db_dir> <id>, put <db_dir> <id> <title> <score> [tags]Read and write a demo record
bench <db_dir> [count]A quick throughput benchmark

Warning

Apart from restore-pitr and inspect-header, the local commands open the engine's typed demo record store (collection default), not the documents store a server writes. For a server's data, use the remote commands, or stop the server and copy its directory.