HeliosDB CLI (hsql)
HeliosDB CLI (hsql)
A powerful interactive command-line interface for HeliosDB, similar to psql and SQLPlus.
Features
- Interactive SQL prompt with readline support
- Command history (persistent across sessions)
- Auto-completion for tables, columns, and SQL keywords
- Multi-line query support
- Multiple output formats (table, CSV, JSON)
- Batch mode for executing SQL files
- Interactive menu system for database administration
- HeliosDB-specific commands for cluster management
Installation
# Build the CLIcargo build --release -p heliosdb-cli
# Install globallycargo install --path heliosdb-cliUsage
Basic Connection
# Connect with connection URLhsql postgres://user:pass@localhost:5432/mydb
# Connect with environment variableexport HELIOSDB_URL="heliosdb://admin@localhost:8443/heliosdb"hsql
# Connect with flagshsql -h localhost -p 8443 -d heliosdb -U adminCommand Line Options
hsql [OPTIONS] [CONNECTION_URL]
Options: -d, --database <DATABASE> Database name to connect to -U, --username <USERNAME> Username for authentication -h, --host <HOST> Host to connect to [default: localhost] -p, --port <PORT> Port to connect to [default: 8443] -c, --command <COMMAND> Execute a single command and exit -f, --file <FILE> Execute commands from file -m, --menu Start in menu mode -F, --format <FORMAT> Output format (table, csv, json) [default: table] -v, --verbose Enable verbose logging --no-color Disable color outputInteractive Mode
Start the interactive shell:
$ hsql _ _ _ _ ____ ____ | | | | ___| (_) ___ ___| _ \| __ ) | |_| |/ _ \ | |/ _ \/ __| | | | _ \ | _ | __/ | | (_) \__ \ |_| | |_) | |_| |_|\___|_|_|\___/|___/____/|____/
HeliosDB Interactive Shell v0.1.0Distributed Multi-Model Database System
Connected to HeliosDBType \? for help, \q to quit
heliosdb=> SELECT * FROM users;Backslash Commands
General Commands
\q- Quit the shell\?or\h- Show help\! COMMAND- Execute shell command
Query Execution
\i FILE- Execute SQL from file\o FILE- Send output to file\o- Reset output to stdout\timing [on|off]- Toggle query timing\watch INTERVAL- Re-run query every INTERVAL seconds
Display Formatting
\x- Toggle expanded output\format [table|csv|json]- Set output format
Database Objects
\l- List databases\d- List tables\d TABLE- Describe table\dt- List tables with sizes\di- List indexes\dv- List vector indexes\du- List users
HeliosDB Specific
\shards- Show shard distribution\replicas- Show replication status\metadata- Show metadata cluster status\vault- Show vault realms\encryption- Show encryption status\perf- Show performance metrics\menu- Open interactive menu
Interactive Menu System
Access the menu with \menu or start with --menu flag:
┌─────────────────────────────────────────────┐│ HeliosDB Administration │├─────────────────────────────────────────────┤│ 1. Database Objects ││ → Tables, Indexes, Schemas ││ 2. Cluster Status ││ → Shards, Replicas, Metadata Nodes ││ 3. Performance Monitoring ││ → Throughput, Latency, Cache Hit Rate ││ 4. Security & Vault ││ → Realms, Encryption, Audit Logs ││ 5. Vector Search ││ → Indexes, Stats, ANN Performance ││ 6. Maintenance ││ → Compaction, Backups, Key Rotation ││ 7. Query Console ││ → Execute SQL ││ 8. Exit │└─────────────────────────────────────────────┘Output Formats
Table Format (Default)
user_id | username | email---------+-----------+-------------------- 1 | alice | alice@example.com 2 | bob | bob@example.com(2 rows)CSV Format
heliosdb=> \format csvheliosdb=> SELECT * FROM users;user_id,username,email1,alice,alice@example.com2,bob,bob@example.comJSON Format
heliosdb=> \format jsonheliosdb=> SELECT * FROM users;[ {"user_id": 1, "username": "alice", "email": "alice@example.com"}, {"user_id": 2, "username": "bob", "email": "bob@example.com"}]Expanded Format
heliosdb=> \xExpanded display is on.heliosdb=> SELECT * FROM users;-[ RECORD 1 ]----------------------------------------user_id | 1username | aliceemail | alice@example.com-[ RECORD 2 ]----------------------------------------user_id | 2username | bobemail | bob@example.comKeyboard Shortcuts
Ctrl+A- Move to beginning of lineCtrl+E- Move to end of lineCtrl+R- Reverse history searchCtrl+L- Clear screenCtrl+D- ExitUp/Down- Navigate historyTab- Auto-complete
Examples
Execute a Single Query
hsql -c "SELECT COUNT(*) FROM users;"Execute SQL File
hsql -f schema.sqlOutput to CSV File
hsql -c "SELECT * FROM users;" -F csv > users.csvWatch Query Results
heliosdb=> \watch 5heliosdb=> SELECT COUNT(*) FROM active_sessions;-- Re-runs every 5 secondsCheck Cluster Health
heliosdb=> \shards shard_id | node_id | status | row_count | size_bytes----------+---------+--------+-----------+------------ 1 | node-1 | active | 1000000 | 52428800 2 | node-2 | active | 950000 | 50331648 3 | node-3 | active | 1050000 | 55574528Monitor Performance
heliosdb=> \perf metric_name | metric_value | unit | timestamp----------------------+--------------+---------+--------------------- queries_per_second | 15420 | qps | 2025-10-11 10:30:00 avg_query_latency | 2.3 | ms | 2025-10-11 10:30:00 cache_hit_rate | 94.5 | percent | 2025-10-11 10:30:00 active_connections | 345 | count | 2025-10-11 10:30:00Configuration
History is stored in:
- Linux:
~/.local/share/heliosdb/hsql_history - macOS:
~/Library/Application Support/heliosdb/hsql_history - Windows:
%APPDATA%\heliosdb\hsql_history
Environment Variables
HELIOSDB_URL- Default connection URLHSQL_HISTORY_SIZE- Maximum history entries (default: 10000)HSQL_COLOR- Enable/disable color output (default: auto)
Building from Source
# Build debug versioncargo build -p heliosdb-cli
# Build release versioncargo build --release -p heliosdb-cli
# Run testscargo test -p heliosdb-cli
# Run the CLIcargo run -p heliosdb-cli -- [OPTIONS]License
Apache-2.0