HeliosDB-Lite Quick Start Guide

Installation

HeliosDB-Lite is available to licensed customers; contact sales@heliosdb.com for access to the source distribution.

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

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

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:

# 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

-- 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). It runs in front of Lite as well as Nano, Full or stock PostgreSQL:

# 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

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

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

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

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

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

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

-- Set compression for table
ALTER TABLE large_table SET COMPRESSION zstd;

-- Check compression stats
\compression large_table

Configuration File

Basic Configuration (config.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

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

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

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

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

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

   EXPLAIN SELECT * FROM large_table WHERE id > 1000;

3. Set appropriate timeouts:

   SET statement_timeout = 30000; -- 30 seconds

4. Tune memory for workload:

   -- Analytics: more memory
   SET work_mem = 131072; -- 128MB
   
   -- OLTP: less memory, more concurrency
   SET work_mem = 4096; -- 4MB

5. Use compression for large tables:

   ALTER TABLE logs SET COMPRESSION zstd;

6. Create materialized views for expensive queries:

   CREATE MATERIALIZED VIEW expensive_query AS
     SELECT... complex query...;
   REFRESH MATERIALIZED VIEW expensive_query INCREMENTALLY;

Troubleshooting

Query too slow

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

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

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
   • SQL Settings Reference
   • Configuration File Reference

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.