---
title: "HeliosDB-Lite REPL Command Reference"
---

# 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](#basic-commands)
- [Schema Inspection](#schema-inspection)
- [Branching Commands](#branching-commands)
- [Time-Travel Commands](#time-travel-commands)
- [AI Commands](#ai-commands)
- [Agent Session Commands](#agent-session-commands)
- [Vector Commands](#vector-commands)
- [Document Commands](#document-commands)
- [Multi-Tenancy Commands](#multi-tenancy-commands)
- [RLS (Row-Level Security)](#rls-row-level-security)
- [CDC (Change Data Capture)](#cdc-change-data-capture)
- [Migration Commands](#migration-commands)
- [Query Analysis](#query-analysis)
- [Server Management](#server-management)
- [High Availability (HA)](#high-availability-ha)
- [Configuration](#configuration)
- [Keyboard Shortcuts](#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:

```bash
# 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

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

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

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

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

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

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

```sql
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)

```sql
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)

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

```sql
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](/docs/lite/features/high-availability/#write-forwarding-from-standbys).

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

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

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

```sql
-- 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](https://www.heliosdb.com/docs/lite/user-guide/sql-reference/) - Complete SQL syntax