Skip to content
NamiDB NamiDB

CLI

The namidb command-line tool wraps the engine for ad-hoc query work: parse, explain, run — against any supported storage backend.

Install

From source:

Terminal window
git clone https://github.com/namidb/namidb.git
cd namidb
cargo install --path crates/namidb-cli

The resulting namidb binary needs no daemon. Without --store, it spins up an ephemeral in-memory namespace for one-shot work. With --store <uri>, it opens a durable namespace on any supported backend.

Subcommands

namidb run

Run a Cypher query.

Terminal window
# Ephemeral, in-memory
namidb run "CREATE (a:Person {name: 'Alice'}), (b:Person {name: 'Bob'})"
namidb run "MATCH (p:Person) RETURN p.name"


# Persistent — any URI scheme is accepted
namidb run --store "file:///var/lib/namidb?ns=prod" \
  "CREATE (a:Person {name: 'Alice'})"


namidb run --store "s3://my-bucket?ns=prod&region=us-west-2" \
  "MATCH (p:Person) RETURN count(*) AS n"


namidb run --store "gs://my-bucket?ns=prod" \
  "MATCH (p:Person) RETURN count(*) AS n"


namidb run --store "az://acct/container?ns=prod" \
  "MATCH (p:Person) RETURN count(*) AS n"

namidb explain

Show the optimised logical plan with cost / selectivity annotations.

Terminal window
namidb explain \
  "MATCH (a:Person)-[:KNOWS]->(b) RETURN b LIMIT 20"


# Full physical-operator tree
namidb explain --verbose \
  "MATCH (a:Person)-[:KNOWS]->(b) RETURN b ORDER BY b.id LIMIT 20"

namidb parse

Show the canonical form of a query (lexer + parser round-trip). Useful for debugging grammar surprises.

Terminal window
namidb parse \
  "MATCH (a:Person)-[:KNOWS]->(b:Person) RETURN b.name LIMIT 5"

URI grammar

The full URI grammar — including endpoint overrides for R2 / MinIO / LocalStack, GCS service-account paths, and Azure emulator mode — is documented at Operations / URI grammar.

Output

Default output is a human-readable table. JSON mode is on the roadmap.

$ namidb run "MATCH (p:Person) RETURN p.name AS name, p.age AS age LIMIT 3"
┌────────┬─────┐
│ name   │ age │
├────────┼─────┤
│ Alice  │ 30  │
│ Bob    │ 25  │
│ Carol  │ 41  │
└────────┴─────┘
3 rows · 12 ms

See also