HeliosDB-Lite 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 Forwarding (TWF)¶

With sync or semi-sync mode, writes to standbys are transparently forwarded 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¶

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;

HeliosDB-Lite REPL Command Reference (v3.5)¶

Table of Contents¶

Basic Commands¶

Dump Formats¶

In-Memory Mode Notes¶

Schema Inspection¶

System Views Available¶

Branching Commands¶

SQL Branch Operations¶

Time-Travel Commands¶

SQL Time-Travel Queries¶

AI Commands¶

Examples¶

Agent Session Commands¶

Agent Session Features¶

Vector Commands¶

Vector Metrics¶

SQL Vector Operations¶

Document Commands¶

Document Features¶

Multi-Tenancy Commands¶

Tenant Management¶

Tenant Quotas¶

Tenant Plans¶

Isolation Levels¶

RLS (Row-Level Security)¶

RLS Example¶

SQL RLS¶

CDC (Change Data Capture)¶

CDC Features¶

Migration Commands¶

Query Analysis¶

Examples¶

SQL EXPLAIN¶

Server Management¶

User Management¶

High Availability (HA)¶

HA System Views¶

pg_replication_status¶

pg_replication_standbys (Primary Only)¶

pg_replication_primary (Standby Only)¶

pg_replication_metrics¶

Transparent Write Forwarding (TWF)¶

Example: Monitor Replication¶

Configuration¶

SQL Settings¶

Keyboard Shortcuts¶

Navigation¶

Editing¶

History¶

Quick Reference Card¶

Most Used Commands¶

SQL Quick Reference¶

See Also¶