Skip to main content
Version: Next

CLI

The sydradb binary provides a small command surface. When invoked with no arguments, it runs the HTTP server.

Command result payloads are written to stdout. Interactive startup/status banners are reserved for stderr and only emitted when stderr is attached to a TTY.

Implementation reference:

serve (default)​

./zig-out/bin/sydradb
./zig-out/bin/sydradb serve

Loads sydradb.toml from the current working directory and starts the HTTP server.

Implementation: server.run dispatch.

pgwire [address] [port]​

Starts the PostgreSQL wire protocol listener.

./zig-out/bin/sydradb pgwire
./zig-out/bin/sydradb pgwire 127.0.0.1 6432

Defaults:

  • address: 127.0.0.1
  • port: 6432

Current support is intentionally narrow and should be treated as a preview alpha surface: startup/auth flow, simple query execution, and a preview prepared/extended flow. COPY and broader compatibility layers remain out of scope for the current alpha cycle.

When a direct prepared/extended query falls outside that preview subset, the current contract is to fail fast with PostgreSQL-style 0A000 (feature not supported) errors rather than silently widening support claims.

Implementation: cmdPgWire.

ingest​

Reads NDJSON from stdin and ingests into the local engine.

cat points.ndjson | ./zig-out/bin/sydradb ingest

Each line uses the same parser as POST /api/v1/ingest:

  • series and ts are required
  • value may be integer or float
  • if value is absent, the first numeric field under fields is used
  • tags participate in canonical series-id derivation

The command flushes before exit, so a successful return means the ingested points are queryable from the local repository state.

The human-readable success summary is only printed when stderr is attached to a TTY, which keeps noninteractive smoke runs and scripts quieter.

Implementation: cmdIngest.

query <series_id> <start_ts> <end_ts>​

Queries a single series over a time range and prints ts,value rows:

./zig-out/bin/sydradb query 123 1694290000 1694310000

The CSV rows are written to stdout.

Implementation: cmdQuery.

compact​

Runs compaction over stored segments.

./zig-out/bin/sydradb compact

Implementation: cmdCompact.

snapshot <dst_dir>​

Writes a snapshot to dst_dir:

./zig-out/bin/sydradb snapshot ./snapshots/2025-01-01

Implementation: cmdSnapshot.

restore <src_dir>​

Restores from a snapshot directory:

./zig-out/bin/sydradb restore ./snapshots/2025-01-01

Implementation: cmdRestore.

stats​

Prints basic counters (including segment counts). In small_pool allocator mode it also prints allocator stats.

./zig-out/bin/sydradb stats

The stats lines are written to stdout.

Implementation: cmdStats.

See also: