---
title: "HeliosDB-Lite Quick Start Guide"
---

# HeliosDB-Lite Quick Start Guide

## Installation

HeliosDB-Lite is available to licensed customers; contact [sales@heliosdb.com](mailto:sales@heliosdb.com) for access to the
source distribution.

```bash
# Build from the unpacked source distribution
cd heliosdb-lite
cargo build --release

# The binary will be at ./target/release/heliosdb-lite
```

## Starting HeliosDB-Lite

### Option 1: Interactive REPL (Single-User Development)

```bash
# In-memory database; add --dump-on-shutdown to dump on exit
heliosdb-lite repl --memory

# Persistent database
heliosdb-lite repl -d ./mydb
```

### Option 2: Server Mode (Multi-User/Production)

```bash
export HELIOSDB_JWT_SECRET="$(openssl rand -hex 32)"
# Start server (foreground)
heliosdb-lite start -d ./mydb --port 5432

# Start as daemon (background)
heliosdb-lite start --daemon -d ./mydb --port 5432

# Check status / stop daemon
heliosdb-lite status
heliosdb-lite stop
```

### Connecting to Server Mode

Once the server is running, connect using any PostgreSQL client:

```bash
# Using psql
psql -h 127.0.0.1 -p 5432

# Using connection string
psql postgresql://127.0.0.1:5432/heliosdb
```

## First Steps in REPL

```sql
-- Get help
heliosdb> \h

-- Create a table
heliosdb> CREATE TABLE users (
       ->   id SERIAL PRIMARY KEY,
       ->   name TEXT NOT NULL,
       ->   email TEXT UNIQUE
       -> );
Query OK

-- Insert data
heliosdb> INSERT INTO users (name, email)
       -> VALUES ('Alice', 'alice@example.com'),
       ->        ('Bob', 'bob@example.com');
Query OK, 2 rows affected

-- Query data
heliosdb> SELECT * FROM users;
 id | name  | email
----+-------+------------------
  1 | Alice | alice@example.com
  2 | Bob   | bob@example.com
(2 rows)

-- List tables
heliosdb> \d
Tables:
  users

-- Describe table
heliosdb> \d users
Table: users
──────────────────────────────────────────────────
Column     Type      Nullable   Primary Key
──────────────────────────────────────────────────
id         Integer   NO         YES
name       Text      NO
email      Text      YES
```

## Essential REPL Commands

### Basic Commands
```
\h              Show help
\d              List all tables
\d <table>      Describe table schema
\dt             List tables with details
\timing         Toggle query timing
\q              Quit
```

### Branches, Snapshots and Materialized Views
```
\branches       List database branches
\snapshots      List time-travel snapshots
\dmv            List materialized views
\compression    Show compression statistics
```

### Settings and Statistics
```
\set            Show all settings
\config         Show configuration
\stats          Show database statistics
\optimize <t>   Optimization recommendations
```

## HeliosProxy Quick Start

HeliosProxy is a standalone, Apache-2.0 PostgreSQL-wire connection router (see the [HeliosProxy documentation](/docs/proxy/)). It runs in front of Lite as well as Nano, Full or stock PostgreSQL:

```bash
# Start HeliosProxy (separate binary)
heliosdb-proxy --config proxy.toml

# Connect through proxy
psql -h 127.0.0.1 -p 6432 -d heliosdb
```

### DistribCache Multi-Tier Caching

DistribCache provides L1/L2/L3 caching optimized for AI workloads:

| Tier | Latency | Best For |
|------|---------|----------|
| L1 Hot | <100μs | Per-connection, exact match |
| L2 Warm | <1ms | Shared, normalized queries |
| L3 Semantic | <10ms | AI workloads, RAG chunks |

```sql
-- Check cache hit rates
SELECT * FROM pg_distribcache_stats();

-- Configure cache for AI workloads
SET distribcache.ai_mode = on;
SET distribcache.conversation_ttl = 3600;
```

## Essential SQL Commands

### Settings Management

```sql
-- Show current settings
SHOW ALL;
SHOW optimizer;
SHOW work_mem;

-- Set timeouts
SET statement_timeout = 30000;  -- 30 seconds

-- Set memory
SET work_mem = 16384;  -- 16MB

-- Enable optimizer
SET optimizer = on;

-- Reset to default
RESET work_mem;
RESET ALL;
```

**REPL command alternatives:**
```
\config         Show configuration
\set            Show REPL variables
\stats          Show database statistics
```

### Time-Travel Queries
```sql
-- Enable time-travel
SET time_travel_enabled = on;

-- Query historical data
SELECT * FROM orders
  AS OF TIMESTAMP '2025-11-23 10:00:00'
  WHERE customer_id = 123;
```

### Database Branching
```sql
-- Create a branch
CREATE DATABASE BRANCH dev FROM main AS OF NOW;

-- Work on branch
USE BRANCH dev;

-- Merge back
MERGE DATABASE BRANCH dev INTO main;
```

### Materialized Views
```sql
-- Create materialized view
CREATE MATERIALIZED VIEW customer_stats AS
  SELECT
    customer_id,
    COUNT(*) as order_count,
    SUM(amount) as total_spent
  FROM orders
  GROUP BY customer_id;

-- Refresh (full, CONCURRENTLY or INCREMENTALLY); automatic refresh is planned
REFRESH MATERIALIZED VIEW customer_stats;

-- Query materialized view
SELECT * FROM customer_stats;
```

### Vector Search
```sql
-- Create table with vector column
CREATE TABLE documents (
  id SERIAL PRIMARY KEY,
  content TEXT,
  embedding VECTOR(384)
);

-- Create vector index
CREATE INDEX ON documents USING hnsw(embedding);

-- Similarity search
SELECT id, content
FROM documents
ORDER BY embedding <-> '[0.1, 0.2, ...]'::vector
LIMIT 10;
```

### Compression
```sql
-- Set compression for table
ALTER TABLE large_table SET COMPRESSION zstd;

-- Check compression stats
\compression large_table
```

## Configuration File

### Basic Configuration (config.toml)

```toml
# Storage
[storage]
path = "./heliosdb-data"
wal_enabled = true
time_travel_enabled = true
cache_size = 536870912  # 512MB

# Server
[server]
listen_addr = "127.0.0.1"
port = 5432
max_connections = 100

# Performance
[performance]
worker_threads = 0  # Auto-detect
simd_enabled = true
parallel_query = true

# Optimizer
[optimizer]
enabled = true
random_page_cost = 4.0  # 1.1 for SSD

# Compression
[compression]
default_type = "Zstd"
level = 3
```

### Start with Configuration

```bash
export HELIOSDB_JWT_SECRET="$(openssl rand -hex 32)"
# Copy example
cp config.example.toml config.toml

# Edit configuration
nano config.toml

# Start with config
heliosdb-lite start --data-dir ./mydb --config config.toml
```

## Common Use Cases

### Analytics Workload

```sql
-- Configure for analytics
SET work_mem = 131072;          -- 128MB
SET shared_buffers = 1048576;   -- 1GB
SET optimizer = on;
SET enable_seqscan = on;

-- Run analytics query
SELECT
  DATE_TRUNC('day', created_at) as date,
  COUNT(*) as order_count,
  SUM(amount) as total_amount
FROM orders
GROUP BY date
ORDER BY date DESC;
```

### OLTP Workload

```sql
-- Configure for OLTP
SET work_mem = 4096;            -- 4MB
SET statement_timeout = 5000;   -- 5 seconds
SET enable_indexscan = on;

-- Transactional queries
BEGIN;
INSERT INTO orders (customer_id, amount) VALUES (123, 99.99);
UPDATE customers SET total_spent = total_spent + 99.99 WHERE id = 123;
COMMIT;
```

### Data Warehouse

```sql
-- Create materialized views for aggregations
CREATE MATERIALIZED VIEW daily_sales AS
  SELECT
    DATE_TRUNC('day', created_at) as date,
    product_id,
    COUNT(*) as sales_count,
    SUM(amount) as revenue
  FROM orders
  GROUP BY date, product_id;

-- Refresh on a schedule (for example from cron)
REFRESH MATERIALIZED VIEW daily_sales INCREMENTALLY;

-- Query aggregated data
SELECT * FROM daily_sales
WHERE date >= CURRENT_DATE - INTERVAL '30 days';
```

### Vector Similarity Search

```sql
-- Configure vector indexes
SET vector_index_type = 'hnsw';
SET hnsw_ef_construction = 200;

-- Create embeddings table
CREATE TABLE embeddings (
  id SERIAL PRIMARY KEY,
  document_id INT,
  embedding VECTOR(384)
);

-- Create index
CREATE INDEX ON embeddings USING hnsw(embedding);

-- Similarity search
SELECT document_id
FROM embeddings
ORDER BY embedding <-> $1::vector
LIMIT 10;
```

## Performance Tips

1. **Enable timing to identify slow queries:**
   ```
   \timing
   ```

2. **Use EXPLAIN to understand query plans:**
   ```sql
   EXPLAIN SELECT * FROM large_table WHERE id > 1000;
   ```

3. **Set appropriate timeouts:**
   ```sql
   SET statement_timeout = 30000; -- 30 seconds
   ```

4. **Tune memory for workload:**
   ```sql
   -- Analytics: more memory
   SET work_mem = 131072; -- 128MB

   -- OLTP: less memory, more concurrency
   SET work_mem = 4096; -- 4MB
   ```

5. **Use compression for large tables:**
   ```sql
   ALTER TABLE logs SET COMPRESSION zstd;
   ```

6. **Create materialized views for expensive queries:**
   ```sql
   CREATE MATERIALIZED VIEW expensive_query AS
     SELECT... complex query...;
   REFRESH MATERIALIZED VIEW expensive_query INCREMENTALLY;
   ```

## Troubleshooting

### Query too slow

```sql
-- Check query plan
EXPLAIN SELECT * FROM table WHERE condition;

-- Compare estimated and actual rows per step
EXPLAIN ANALYZE SELECT * FROM table WHERE condition;

-- Increase work memory
SET work_mem = 16384;

-- Enable timing
\timing
```

### Out of memory

```sql
-- Reduce work_mem
SET work_mem = 2048;

-- Disable parallel execution
SET parallel_query = off;

-- Check current settings
SHOW work_mem;
SHOW shared_buffers;
```

### Connection issues

```bash
export HELIOSDB_JWT_SECRET="$(openssl rand -hex 32)"
# Check server status
\server status

# Check configuration
\config

# Restart server
heliosdb-lite start --data-dir ./mydb --config config.toml
```

## Next Steps

1. **Read the documentation:**
   - [REPL Command Reference](/docs/lite/user-guide/repl-commands/)
   - [SQL Settings Reference](/docs/lite/user-guide/sql-settings/)
   - [Configuration File Reference](/docs/lite/user-guide/configuration/)

2. **Explore features:**
   - Time-travel queries
   - Database branching
   - Materialized views
   - Vector search

3. **Optimize performance:**
   - Use EXPLAIN for query plans
   - Create appropriate indexes
   - Tune memory settings
   - Enable compression

   - Configure TLS/SSL
   - Enable authentication
   - Record changes to sensitive tables with triggers (built-in audit logging is planned)
   - Configure backups

## Resources

- **Documentation**: `/docs/`
- **Examples**: `/examples/`
- **Configuration**: `config.example.toml`
- **Deployment Modes**: `docs/guides/MODE_SELECTION_GUIDE.md`
- **Product page**: https://www.heliosdb.com/lite.html
- **Issues**: support@heliosdb.com

## Getting Help

```
-- In REPL
\h              General help
\h <command>    Command-specific help

-- Show settings
SHOW ALL;

-- Show configuration
\config

-- Show statistics
\stats
```

## Quick Reference Card

| Task | REPL | SQL | Config |
|------|------|-----|--------|
| List tables | `\d` | `SELECT * FROM pg_tables` | - |
| Set timeout | `\set statement_timeout 30000` | `SET statement_timeout = 30000;` | `[storage] query_timeout_ms = 30000` |
| Enable optimizer | `\set optimizer on` | `SET optimizer = on;` | `[optimizer] enabled = true` |
| Time-travel | `\snapshots` | `AS OF TIMESTAMP '...'` | `[storage] time_travel_enabled = true` |
| Compression | `\compression` | `ALTER TABLE... SET COMPRESSION` | `[compression] default_type = "Zstd"` |
| View config | `\config` | `SHOW ALL;` | - |
| Get help | `\h` | - | - |

---

Start with `\h` in the REPL.