HeliosDB-Lite REPL Command Reference

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; start from the command prompt with --dump-on-shutdown
• 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>	Placeholder; automatic index recommendations are planned
\optimize <table>	Prints EXPLAIN hints for the table; automatic recommendations are planned

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()" 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());

-- 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 state
\Server state	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
is_read_only	true on a standby
current_lsn	Current log sequence number
standby_count	Connected standbys (primary)
primary_host	Primary this node replicates from (standby)
listen_addr	Listen address
replication_port	WAL streaming port
started_at	Time the node started

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
primary_node_id	Primary identifier
primary_address	Primary address
connection_state	disconnected, connecting, connected, streaming, error
primary_lsn	Primary’s current LSN
local_lsn	This standby’s LSN
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;

One row per metric, with the columns metric_name, metric_value and description. Metrics include wal_writes, wal_bytes_written, records_replicated, bytes_replicated, heartbeats_sent, heartbeats_received, reconnect_count, current_lsn, standby_count and ha_enabled.

Write Forwarding from Standbys

With sync or semi-sync mode, a standby forwards writes sent with the simple query protocol (for example from psql) to the primary. Prepared statements (extended query protocol) and REST calls are not forwarded, and forwarding needs trust authentication on the primary; see High Availability.

-- 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