Shell¶

A fast, lightweight command-line shell for exploring, scripting, and debugging Velr databases.

The shell is designed to:

• Start instantly — perfect for one-off commands, scripts, and automation.
• Provide a clean interactive REPL for Cypher exploration.
• Integrate smoothly with Bash, pipes, cron, Makefiles, and CI.
• Support multiple output formats (plain, styled, csv, tsv, ndjson).
• Offer query introspection via EXPLAIN to show the generated SQL.

Overview¶

The shell operates in three modes:

1. Interactive mode — the default REPL experience
2. Execute mode (-e/--execute) — run a single query and exit
3. Stdin mode — read an entire query from pipes or here-docs

You can work on either:

• An in-memory database (default), or
• A persistent file-backed database (pass a path)

All queries, including EXPLAIN, run through the same embedded engine as the Rust and Python drivers.

Basic Usage¶

# In-memory
velr

# File-backed
velr my.db

Run Cypher directly in the REPL:

> CREATE (:User {name:'Alice'});
> MATCH (u:User) RETURN u.name;

Every query prints results and a timing line:

Query executed in 0.431 ms

Startup is essentially instantaneous — there is no server process or daemon. This makes the shell ideal for Bash scripting.

EXPLAIN — Inspect the Generated SQL Plan¶

Velr lets you inspect how a Cypher query is lowered into SQLite by prefixing any query with:

EXPLAIN <cypher-query>;

Example:

> EXPLAIN MATCH (u:User) RETURN u.name;

The shell prints the SQL plan Velr produces internally. This is extremely useful for:

• Understanding join structure
• Debugging variable-length paths
• Checking index usage
• Optimizing complex graph queries
• Learning how Velr maps Cypher → SQL

You can pipe EXPLAIN output into other tools for analysis:

velr my.db -e "EXPLAIN MATCH (n) RETURN n" \
  | grep -v '^Query executed in ' \
  | less

Modes¶

1. Interactive Mode (REPL)¶

velr
velr my.db

Inside the REPL:

• Enter Cypher queries
• Use EXPLAIN ... to inspect plans
• Use commands starting with : (see below)
• Exit with Ctrl+C, Ctrl+D, or an empty line

2. Execute Mode (-e/--execute)¶

velr -e "MATCH (u:User) RETURN u"
velr my.db -e "EXPLAIN MATCH (u:User) RETURN u"

This mode:

• Runs exactly one query
• Prints results
• Exits immediately

Great for scripts:

if velr my.db -e "MATCH (u:User {name:'Alice'}) RETURN u"; then
    echo "Alice exists"
fi

3. Stdin Mode¶

When stdin is non-empty, Velr reads all of it as a query:

echo "MATCH (n) RETURN n" | velr my.db

Or with a here-doc:

velr my.db << 'EOF'
EXPLAIN MATCH (u:User)
RETURN u.name, u.age
EOF

If stdin is empty, the shell falls back to the REPL.

Output Formats (-f/--format)¶

Examples:

velr my.db -f csv -e "MATCH (u) RETURN u.name, u.age"
velr my.db -f ndjson -e "EXPLAIN MATCH (n) RETURN n"

Strip the timing line for scripts:

velr my.db -f ndjson -e "..." | grep -v '^Query executed in '

Shell Commands (REPL-only)¶

Commands must begin with :.

:source <file>¶

Executes a file containing Cypher:

> :source seed.cypher
Load file: seed.cypher
Query executed in 2.847 ms

:help / :h¶

Shows available commands:

> :help
Available commands: :source, ctrl+c to exit

Using the Shell in Scripts¶

Because it starts instantly, velr is very comfortable for automation.

Setup / migrations¶

#!/usr/bin/env bash
set -euo pipefail

DB="app.db"

velr "$DB" -e "
CREATE (:User {name:'Root'});
"

velr "$DB" << 'EOF'
UNWIND [
  {name:'Alice', age:30},
  {name:'Bob',   age:25}
] AS r
CREATE (:User {name:r.name, age:r.age});
EOF

Export to CSV¶

velr my.db -f csv -e "
MATCH (u:User)
RETURN u.name AS name, u.age AS age
" \
  | grep -v '^Query executed' \
  > users.csv

Inspect the SQL plan of a query¶

velr my.db -e "
EXPLAIN MATCH path = (a)-[:KNOWS*1..3]->(b)
RETURN a.name, b.name, length(path)
"

Summary¶

• Instant startup — great for automation and short-lived commands
• 3 modes: interactive, execute, stdin
• Multiple output formats for humans and machines
• :source for loading scripts
• EXPLAIN to inspect the SQL plan behind any query
• Built for scripting, piping, cron jobs, and ad-hoc analysis
• Works with both in-memory and file-backed databases

If you want, I can also generate:

• A “Shell Quickstart” page
• A “Performance Tuning with EXPLAIN” page
• A cookbook of shell examples for migrations, exports, and debugging

Just say the word.