HeliosDB Nano REPL Command Reference (v3.5)

HeliosDB Nano REPL Command Reference (v3.5)

Complete reference for all REPL meta commands. Type \h for help or \h <category> for category-specific help.

Table of Contents

• Basic Commands
• Schema Inspection
• Branching Commands
• Time-Travel Commands
• AI Commands
• Agent Session Commands
• Vector Commands
• Document Commands
• Multi-Tenancy Commands
• RLS (Row-Level Security)
• CDC (Change Data Capture)
• Migration Commands
• Query Analysis
• Server Management
• High Availability (HA)
• Configuration
• Keyboard Shortcuts

---

Basic Commands

Command	Description
\q, \quit, \exit	Exit the REPL
\h, \help, \?	Show help overview
\h <category>	Show help for category (basics, schema, branching, time-travel, vectors, documents, agents, ai, tenants, settings, examples, sql)
\timing	Toggle query execution timing
\e, \edit	Open last query in editor
\dump [file]	Dump database to file (default: backup.heliodump)
\telemetry	Show telemetry/statistics
\stats	Show database statistics

Dump Formats

The \dump command exports database contents:

# Dump to default file (backup.heliodump)
\dump

# Dump to specific file
\dump /path/to/backup.heliodump

# View dump file info
\dump --info backup.heliodump

In-Memory Mode Notes

When running in --memory mode:

• Use --dump-on-shutdown flag to auto-dump before exit
• Use --dump-file <path> to specify dump location
• Data is lost on exit unless dumped
• Use \dump command during session for manual backups

---

Schema Inspection

Command	Description
\d	List all tables
\d <table>	Describe table schema
\dt	List tables with column counts
\dS	List system views
\dS <view>	Describe system view schema
\dmv	List materialized views
\dmv <view>	Describe materialized view
\compression	Show compression statistics
\compression <table>	Show table compression stats
\indexes <table>	Show index recommendations
\optimize <table>	Show optimization suggestions

System Views Available

SELECT * FROM pg_database_branches();   -- Branch metadata
SELECT * FROM pg_mv_staleness();        -- MV refresh status
SELECT * FROM pg_vector_index_stats();  -- Vector index stats
SELECT * FROM pg_tenant_usage();        -- Tenant resource usage
SELECT * FROM pg_rls_policies();        -- RLS policy definitions
SELECT * FROM pg_cdc_events();          -- CDC event log
SELECT * FROM pg_smfi_status();         -- SMFI system status
SELECT * FROM pg_smfi_table_stats();    -- Per-table SMFI stats
SELECT * FROM pg_speculative_filters(); -- Auto-created filters

---

Branching Commands

Command	Description
\branches	List all database branches
\use <branch>	Switch to branch
\show branch	Show current branch
\snapshots	Show time-travel snapshot info

SQL Branch Operations

-- Create branch from current state
CREATE DATABASE BRANCH dev FROM main;

-- Create branch at specific point
CREATE DATABASE BRANCH hotfix FROM main AS OF TIMESTAMP '2025-01-01';

-- Merge branch
MERGE DATABASE BRANCH dev INTO main;

-- Drop branch
DROP DATABASE BRANCH dev;

-- Switch branch (alternative to \use)
USE BRANCH dev;

---

Time-Travel Commands

Command	Description
\snapshots	Show time-travel capabilities
\show lsn	Show current LSN (Log Sequence Number)

SQL Time-Travel Queries

-- Query by timestamp
SELECT * FROM orders AS OF TIMESTAMP '2025-01-15 10:00:00';

-- Query by transaction ID
SELECT * FROM orders AS OF TRANSACTION 12345;

-- Query by SCN (System Change Number)
SELECT * FROM orders AS OF SCN 50000;

---

AI Commands

Command	Description
\ai templates	List available schema templates
\ai template <name>	Show template details
\ai infer <format>	Infer schema from data (json, csv, parquet)
\ai generate <description>	Generate schema from description
\ai optimize <table>	Get AI-powered optimization suggestions
\ai models	List available AI models
\ai embed <text>	Generate embedding for text
\ai compare-schema <s1> <s2>	Compare two table schemas

Examples

\ai templates
\ai template e-commerce
\ai infer json
\ai generate "user profiles with social features"
\ai optimize users
\ai models
\ai embed "Hello world"
\ai compare-schema users_v1 users_v2

---

Agent Session Commands

Command	Description
\sessions	List all agent sessions
\session new <name>	Create new agent session
\session <id>	Show session details
\session delete <id>	Delete agent session
\chat <session_id>	Enter chat mode with session
\session clear <id>	Clear session messages
\session fork <id> <name>	Fork session with history
\session context <id>	Show session context/state
\session memory <id> <query>	Semantic search in session memory
\session summarize <id>	Generate session summary

Agent Session Features

• Persistent conversation context
• Multi-turn AI interactions
• Schema-aware responses
• Natural language to SQL conversion
• Session forking for experimentation
• Semantic memory search

---

Vector Commands

Command	Description
\vectors	List vector stores
\vector <name>	Show vector store details
\vector create <name> <dims> [metric]	Create vector store
\vector delete <name>	Delete vector store
\vector stats <name>	Show vector index statistics

Vector Metrics

• cosine (default) - Cosine similarity
• euclidean - Euclidean distance
• dot - Dot product

SQL Vector Operations

-- Create vector column
ALTER TABLE items ADD COLUMN embedding VECTOR(384);

-- Insert vectors
INSERT INTO items (name, embedding) VALUES ('item1', '[0.1, 0.2, ...]');

-- Vector similarity search
SELECT * FROM items
ORDER BY embedding <-> '[0.1, 0.2, ...]'
LIMIT 10;

-- Hybrid search (vector + text)
SELECT * FROM items
WHERE content LIKE '%keyword%'
ORDER BY embedding <-> '[0.1, 0.2, ...]'
LIMIT 10;

---

Document Commands

Command	Description
\collections	List document collections
\collection <name>	Show collection details
\docs <collection>	List documents in collection
\doc <collection> <id>	Show document details
\search <query>	Search across all documents
\doc chunks <collection> <id>	Show document chunks
\doc rechunk <collection> <id> <size>	Re-chunk document
\rag <collection> <query> [k]	RAG-style search with context

Document Features

• Automatic chunking for RAG
• Vector embeddings for semantic search
• Metadata filtering
• Full-text search integration
• Document re-chunking for optimization
• RAG search with relevance context

---

Multi-Tenancy Commands

Tenant Management

Command	Description
\tenants	List all tenants
\tenant create <name> [plan] [isolation]	Create tenant
\tenant use <id/name>	Switch tenant context
\tenant <id/name>	Show tenant info
\tenant current	Show current tenant context
\tenant clear	Clear tenant context
\tenant delete <id/name>	Delete tenant

Tenant Quotas

Command	Description
\tenant quota <id/name>	Show tenant quotas
\tenant quota set <id> storage=N connections=N qps=N	Set quotas
\tenant usage <id/name>	Show resource usage

Tenant Plans

Command	Description
\tenant plans	List available plans
\tenant plan info <name>	Show plan details
\tenant plan create <name> tier=N storage=N connections=N qps=N	Create plan
\tenant plan edit <id> <field>=<value>	Edit plan
\tenant plan enable <id>	Enable plan
\tenant plan disable <id>	Disable plan
\tenant plan delete <id>	Delete plan
\tenant plan <tenant> <plan>	Assign plan to tenant

Isolation Levels

• shared - Shared database, logical isolation via tenant_id
• schema - Per-tenant schema isolation
• database - Full database isolation

---

RLS (Row-Level Security)

Command	Description
\tenant rls create <table> <policy> <expression> [command]	Create RLS policy
\tenant rls list <table>	List table policies
\tenant rls delete <table> <policy>	Delete policy

RLS Example

\tenant rls create orders tenant_policy "tenant_id = current_tenant_id()" SELECT
\tenant rls list orders

SQL RLS

-- Enable RLS on table
ALTER TABLE orders ENABLE ROW LEVEL SECURITY;

-- Create policy
CREATE POLICY tenant_isolation ON orders
  USING (tenant_id = current_tenant_id());

-- List policies
SELECT * FROM pg_rls_policies();

---

CDC (Change Data Capture)

Command	Description
\tenant cdc [limit]	Show recent CDC events
\tenant cdc export <file>	Export CDC events to file

CDC Features

• Automatic change tracking
• Per-tenant event isolation
• Export for external systems
• Migration support

---

Migration Commands

Command	Description
\tenant migrate to <target>	Migrate tenant to new location
\tenant migrate status <tenant>	Check migration status

---

Query Analysis

Command	Description
\explain <query>	Show query execution plan
\profile <query>	Profile query with timing

Examples

\explain SELECT * FROM orders WHERE total > 100;
\profile SELECT COUNT(*) FROM large_table;

SQL EXPLAIN

EXPLAIN SELECT * FROM orders WHERE customer_id = 1;
EXPLAIN ANALYZE SELECT * FROM orders WHERE total > 100;
EXPLAIN (FORMAT JSON) SELECT * FROM orders;

---

Server Management

Command	Description
\server	Show server status
\server status	Detailed server info
\server start	Start server (from REPL)
\server stop	Stop server
\ssl, \ssl status	Show SSL/TLS status

User Management

Command	Description
\user, \user list	List users
\user add <name>	Add user
\user remove <name>	Remove user
\password <user>	Change password

---

High Availability (HA)

HA System Views

View	Description
pg_replication_status	Node configuration and role
pg_replication_standbys	Connected standbys (primary only)
pg_replication_primary	Primary connection (standbys only)
pg_replication_metrics	Performance counters

pg_replication_status

SELECT * FROM pg_replication_status;

Column	Description
node_id	Unique node identifier
role	primary, standby, observer, standalone
sync_mode	async, semi-sync, sync
listen_address	Host and port
replication_port	WAL streaming port
current_lsn	Current log sequence number
is_read_only	true/false
standby_count	Connected standbys (primary)
uptime_seconds	Uptime

pg_replication_standbys (Primary Only)

SELECT * FROM pg_replication_standbys;

Column	Description
node_id	Standby identifier
address	Connection address
state	connecting, streaming, catching_up, synced, disconnected
lag_bytes	Replication lag in bytes
lag_ms	Replication lag in milliseconds
last_heartbeat	Last heartbeat received

pg_replication_primary (Standby Only)

SELECT * FROM pg_replication_primary;

Column	Description
node_id	Primary identifier
address	Primary address
state	disconnected, connecting, connected, streaming, error
lag_bytes	Replication lag in bytes
lag_ms	Replication lag in milliseconds
fencing_token	Split-brain protection token

pg_replication_metrics

SELECT * FROM pg_replication_metrics;

Column	Description
wal_writes	Total WAL write operations
wal_bytes_written	Total WAL bytes written
records_replicated	Records sent to standbys
bytes_replicated	Bytes sent to standbys
heartbeats_sent	Health checks sent
heartbeats_received	Health checks received
reconnect_count	Number of reconnections

Transparent Write Routing (TWR)

With sync or semi-sync mode, writes to standbys are transparently routed to primary:

-- Connect to standby, execute INSERT (forwarded to primary)
INSERT INTO users VALUES (3, 'Charlie');
-- Result: INSERT 0 1 (executed on primary)

-- SELECT always executes locally on standby
SELECT * FROM users;

Sync Mode	SELECT	INSERT/UPDATE/DELETE
sync	Local	Forward to primary
semi-sync	Local	Forward to primary
async	Local	Rejected (read-only)

Example: Monitor Replication

-- Check if standbys are in sync
SELECT
    node_id,
    CASE
        WHEN lag_ms < 1000 THEN 'IN_SYNC'
        WHEN lag_ms < 60000 THEN 'CATCHING_UP'
        ELSE 'LAGGING'
    END as status,
    lag_ms
FROM pg_replication_standbys;

-- View node info
SELECT node_id, role, current_lsn FROM pg_replication_status;

---

Configuration

Command	Description
\config	Show current configuration
\config reload	Reload config from file
\set	Show session variables
\set <var> <value>	Set session variable

SQL Settings

-- Show all settings
SHOW ALL;

-- Show specific setting
SHOW statement_timeout;

-- Set session variable
SET statement_timeout = 30000;
SET optimizer = off;

---

Keyboard Shortcuts

Navigation

Key	Action
Ctrl-A / Home	Beginning of line
Ctrl-E / End	End of line
Ctrl-B / Left	Back one character
Ctrl-F / Right	Forward one character
Alt-B	Back one word
Alt-F	Forward one word

Editing

Key	Action
Ctrl-D	Exit (at empty prompt)
Ctrl-C	Cancel multi-line input
Ctrl-L	Clear screen
Ctrl-U	Delete to line start
Ctrl-K	Delete to line end
Ctrl-W	Delete word before cursor

History

Key	Action
Up / Ctrl-P	Previous command
Down / Ctrl-N	Next command
Ctrl-R	Reverse search history
Tab	Auto-complete

---

Quick Reference Card

Most Used Commands

\q              Exit
\h              Help
\d              List tables
\d <table>      Describe table
\timing         Toggle timing
\branches       List branches
\use <branch>   Switch branch
\tenants        List tenants
\tenant use <t> Switch tenant
\explain <sql>  Query plan

SQL Quick Reference

-- Create table
CREATE TABLE t (id INT PRIMARY KEY, name TEXT);

-- Insert
INSERT INTO t VALUES (1, 'test');

-- Query
SELECT * FROM t WHERE id = 1;

-- Time-travel
SELECT * FROM t AS OF TIMESTAMP '2025-01-01';

-- Vector search
SELECT * FROM t ORDER BY vec <-> '[0.1,0.2]' LIMIT 5;

---

See Also

• SQL Reference - Complete SQL syntax
• Config Reference - Configuration options
• SQL Settings Reference - Runtime settings