Getting Started with HeliosDB-Lite

Estimated Time: 30 minutes

Introduction
Installation
Your First Database
REPL vs Server Mode
Quick Feature Tour
Next Steps

Introduction

What is HeliosDB-Lite?

HeliosDB-Lite is a PostgreSQL-compatible embedded database written in Rust that combines SQLite-style embedding with PostgreSQL compatibility. It’s designed for developers who need a SQL database without the operational overhead of managing a separate database server.

Key Characteristics:

Embedded: Runs directly in your application process (like SQLite)
PostgreSQL Compatible: 95%+ PostgreSQL 17 syntax compatibility
Dual Mode: Use as embedded library OR standalone server
Feature-Rich: Vector search, time-travel, branching, encryption
Zero Dependencies: Single binary, no external database server needed

Key Features Overview

Feature	Description	Use Case
Embedded Mode	In-process database, no network overhead	Desktop apps, mobile, IoT
Server Mode	PostgreSQL wire protocol server	Replace PostgreSQL for small-medium apps
Vector Search	Built-in semantic search with HNSW	AI/ML applications, RAG pipelines
Product Quantization	Compact vector codes for lower index memory	Memory-efficient vector storage
Time-Travel	Query historical data at any point in time	Auditing, debugging, analytics
Branching	Git-like database branches	Safe schema changes, testing
Encryption (TDE)	AES-256-GCM transparent encryption	HIPAA, GDPR, SOC2 compliance
Materialized Views	Stored query results, refreshed in full or incrementally	Dashboards, analytics

When to Use HeliosDB-Lite

Perfect for:

Desktop and mobile applications
Edge computing and IoT devices
Microservices with embedded databases
AI/ML applications with vector search
Applications requiring audit trails
Development and testing environments
Small to medium web applications

Not ideal for:

Multi-node clustering (use full HeliosDB)
Extremely high write throughput (>100K writes/sec)
Distributed transactions across nodes

Installation

Prerequisites

Rust: 1.75 or later
Operating System: Linux, macOS, or Windows
Disk Space: ~500 MB for build, ~50 MB for binary

HeliosDB-Lite is available to licensed customers; contact sales@heliosdb.com for access to the source distribution. It is not published on crates.io or Docker Hub.

Option 1: Build from Source (Recommended)

# Unpack the licensed source distribution, then:
cd heliosdb-lite

# Build release binary
cargo build --release

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

Expected Output (first lines):

PostgreSQL-compatible database with vector search and encryption

Usage: heliosdb-lite <COMMAND>

Option 2: Install via Cargo

# Install from the unpacked source distribution
cargo install --path ./heliosdb-lite

# Verify installation
heliosdb-lite --help

Option 3: Docker

# Build the image inside the unpacked source distribution
docker build -f deployment/docker/Dockerfile -t heliosdb-lite:latest .

# Run interactive REPL
docker run -it --rm heliosdb-lite:latest repl --memory

# Run server mode
docker run -p 5432:5432 -e HELIOSDB_JWT_SECRET="$(openssl rand -hex 32)" \
  heliosdb-lite:latest start --memory --listen 0.0.0.0 --port 5432

Verify Installation

# Show help (the CLI has no --version flag)
heliosdb-lite --help

# Test REPL (in-memory database); type \version to print the build version
heliosdb-lite repl --memory

In the REPL, type:

CREATE TABLE test (id INT, name TEXT);
INSERT INTO test VALUES (1, 'Hello HeliosDB');
SELECT * FROM test;
\q

If the inserted rows are returned, the installation works.

Your First Database

Using the Interactive REPL

The REPL (Read-Eval-Print Loop) is the fastest way to explore HeliosDB-Lite.

Start an In-Memory Database

heliosdb-lite repl --memory

Output:

HeliosDB-Lite
Type \h for help, \q to quit

heliosdb>

Create Your First Table

-- Create a users table
CREATE TABLE users (
    id INT PRIMARY KEY,
    name TEXT NOT NULL,
    email TEXT NOT NULL,
    age INT
);

Output: Query OK (0.002s)

Insert Data

-- Insert individual records
INSERT INTO users VALUES (1, 'Alice Johnson', 'alice@example.com', 30);
INSERT INTO users VALUES (2, 'Bob Smith', 'bob@example.com', 25);
INSERT INTO users VALUES (3, 'Charlie Brown', 'charlie@example.com', 35);

Output: Inserted 1 row (0.001s) (for each INSERT)

Query Data

-- Select all users
SELECT * FROM users;

-- Select with WHERE clause
SELECT name, email FROM users WHERE age > 28;

-- Aggregates
SELECT COUNT(*), AVG(age) FROM users;

-- Order and limit
SELECT * FROM users ORDER BY age DESC LIMIT 2;

Example Output:

 id | name          | email                | age
----|---------------|----------------------|-----
  1 | Alice Johnson | alice@example.com    |  30
  2 | Bob Smith     | bob@example.com      |  25
  3 | Charlie Brown | charlie@example.com  |  35

(3 rows, 0.003s)

Update and Delete

-- Update data
UPDATE users SET age = 31 WHERE name = 'Alice Johnson';

-- Delete data
DELETE FROM users WHERE age < 28;

-- Verify changes
SELECT * FROM users;

REPL Meta-Commands

HeliosDB-Lite supports PostgreSQL-style meta-commands:

\h                  -- Show help
\d                  -- List tables
\d users            -- Describe table 'users'
\dS                 -- List system views
\l                  -- List databases/branches
\q                  -- Quit REPL

Using a Persistent Database

To save data between sessions, use a persistent file:

# Create database in current directory
heliosdb-lite repl -d ./mydb.helio

# Or specify full path
heliosdb-lite repl -d /path/to/my/database.helio

All commands work the same, and the data persists after quitting.

Basic SQL Operations Summary

Operation	SQL Syntax	Example
Create Table	`CREATE TABLE name (columns)`	`CREATE TABLE users (id INT, name TEXT)`
Insert	`INSERT INTO table VALUES (...)`	`INSERT INTO users VALUES (1, 'Alice')`
Select	`SELECT columns FROM table`	`SELECT * FROM users WHERE age > 25`
Update	`UPDATE table SET col = val`	`UPDATE users SET age = 31 WHERE id = 1`
Delete	`DELETE FROM table WHERE...`	`DELETE FROM users WHERE age < 18`
Aggregates	`SELECT COUNT(*), SUM(col), AVG(col)`	`SELECT AVG(age) FROM users`
Join	`SELECT... FROM t1 JOIN t2 ON...`	`SELECT * FROM users JOIN orders ON users.id = orders.user_id`
Group By	`SELECT col, COUNT(*) GROUP BY col`	`SELECT region, SUM(sales) FROM orders GROUP BY region`

REPL vs Server Mode

HeliosDB-Lite offers two ways to work with a database.

REPL Mode

Use When: You want an interactive SQL shell on a local data directory, for exploration, scripts or single-user tools.

heliosdb-lite repl -d ./mydb      # persistent
heliosdb-lite repl --memory       # in-memory

Embedding the engine in your own application process is available to licensed customers with the source distribution.

Server Mode (PostgreSQL Protocol)

Use When: You want to connect from multiple applications or use PostgreSQL clients.

Benefits:

Language-agnostic (use any PostgreSQL client)
Multiple concurrent connections
Drop-in PostgreSQL replacement
Use with ORMs (SQLAlchemy, Diesel, etc.)

Start the Server

# Signing secret for the REST API (required)
export HELIOSDB_JWT_SECRET="$(openssl rand -hex 32)"

# Start server on default port (5432)
heliosdb-lite start --data-dir ./mydb

# Start on custom port
heliosdb-lite start --data-dir ./mydb --port 5433

# Start with password authentication
heliosdb-lite start --data-dir ./mydb --auth scram-sha-256 --password "$HELIOSDB_ADMIN_PASSWORD"

Connect with psql

# Connect with psql
psql postgresql://localhost:5432/mydb

# Or with authentication
psql postgresql://username:password@localhost:5432/mydb

Once connected, use standard PostgreSQL commands:

-- Create table
CREATE TABLE orders (
    id SERIAL PRIMARY KEY,
    customer_id INT NOT NULL,
    total DECIMAL(10, 2),
    created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP
);

-- Insert data
INSERT INTO orders (customer_id, total) VALUES (1, 299.99);

-- Query
SELECT * FROM orders WHERE customer_id = 1;

Connect from Python

import psycopg2

# Connect to HeliosDB-Lite server
conn = psycopg2.connect(
    host="localhost",
    port=5432,
    database="mydb",
    user="postgres",  # default user
    password=""
)

# Create cursor
cur = conn.cursor()

# Execute query
cur.execute("SELECT * FROM users WHERE age > %s", (25,))
rows = cur.fetchall()

for row in rows:
    print(row)

# Cleanup
cur.close()
conn.close()

Connect from Node.js

const { Client } = require('pg');

// Connect to HeliosDB-Lite server
const client = new Client({
  host: 'localhost',
  port: 5432,
  database: 'mydb',
  user: 'postgres',
  password: ''
});

await client.connect();

// Execute query
const result = await client.query('SELECT * FROM users WHERE age > $1', [25]);
console.log(result.rows);

await client.end();

Comparison Table

Feature	REPL Mode	Server Mode
Setup	`heliosdb-lite repl`	`heliosdb-lite start`
Performance	No network hop	Network overhead
Concurrency	Single process	Multiple clients
Language Support	SQL shell	Any PostgreSQL client, REST
Use Case	Exploration, scripts	Multi-app, web services

Quick Feature Tour

Now that you understand the basics, let’s explore HeliosDB-Lite’s unique features.

Vector Search

Store and search embeddings for semantic search, recommendations, and RAG pipelines.

Example: Semantic Document Search

-- Create table with vector column
CREATE TABLE documents (
    id SERIAL PRIMARY KEY,
    title TEXT,
    content TEXT,
    embedding VECTOR(384)  -- 384-dimensional vector
);

-- Create HNSW index for fast similarity search
CREATE INDEX idx_docs_embedding ON documents
USING hnsw (embedding vector_cosine_ops)
WITH (m = 16, ef_construction = 200);

-- Insert document with embedding (from your embedding model)
INSERT INTO documents (title, content, embedding) VALUES (
    'Introduction to Databases',
    'A database is an organized collection of data...',
    '[0.023, -0.145, 0.892, ...]'::VECTOR(384)
);

-- Semantic search: find similar documents
SELECT
    id,
    title,
    embedding <=> '[0.015, -0.120, 0.850, ...]'::VECTOR(384) AS distance
FROM documents
ORDER BY distance ASC
LIMIT 10;

With Product Quantization:

-- Create index with PQ compression
CREATE INDEX idx_docs_pq ON documents
USING hnsw (embedding vector_cosine_ops)
WITH (
    m = 16,
    ef_construction = 200,
    quantization = 'product',
    pq_subquantizers = 8,
    pq_centroids = 256
);

-- Same queries, with less index memory

In HeliosDB Nano, Product Quantization cut resident vector-index RAM by about 16x at recall-safe defaults (recall@10 0.987 vs 0.989; internal tests, Nano 3.32.1 vs an unquantized index). No Lite-specific measurement has been published.

Learn More: See Vector Search Tutorial

Time-Travel Queries

Access historical data at any point in time without manual snapshots.

Example: Audit Historical Changes

-- Create table
CREATE TABLE prices (
    product_id INT,
    price DECIMAL(10, 2),
    updated_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP
);

-- Insert initial price
INSERT INTO prices VALUES (1, 99.99, NOW());

-- Update price multiple times
UPDATE prices SET price = 89.99, updated_at = NOW() WHERE product_id = 1;
UPDATE prices SET price = 79.99, updated_at = NOW() WHERE product_id = 1;

-- Query current price
SELECT * FROM prices WHERE product_id = 1;
-- Returns: (1, 79.99, 2025-12-01 15:30:00)

-- Query price as of yesterday
SELECT * FROM prices
AS OF TIMESTAMP '2025-11-30 12:00:00'
WHERE product_id = 1;
-- Returns: (1, 99.99, 2025-11-30 10:00:00)

-- Compare current vs historical
SELECT
    current.price AS current_price,
    historical.price AS historical_price,
    current.price - historical.price AS price_change
FROM prices current
JOIN prices AS OF TIMESTAMP '2025-11-30 00:00:00' historical
  ON current.product_id = historical.product_id
WHERE current.product_id = 1;

Learn More: See the Time Travel Queries Tutorial

Database Branching

Git-like branches for safe schema changes and testing.

Example: Test Schema Changes

-- Create development branch
CREATE BRANCH dev FROM main;

-- Switch to dev branch
USE BRANCH dev;

-- Safely test schema changes
ALTER TABLE users ADD COLUMN preferences JSONB;
INSERT INTO users VALUES (999, 'Test User', 'test@example.com', 25, '{"theme": "dark"}');

-- Test your changes
SELECT * FROM users WHERE id = 999;

-- If satisfied, merge back to main
USE BRANCH main;
MERGE BRANCH dev INTO main;

-- Clean up
DROP BRANCH dev;

Learn More: See the Database Branching Tutorial

Materialized Views

Pre-compute expensive queries for instant dashboard performance.

Example: Real-Time Dashboard

-- Create materialized view
CREATE MATERIALIZED VIEW sales_dashboard AS
SELECT
    DATE_TRUNC('day', order_date) AS day,
    COUNT(*) AS total_orders,
    SUM(amount) AS total_revenue,
    AVG(amount) AS avg_order_value
FROM orders
GROUP BY DATE_TRUNC('day', order_date);

-- Query is instant (no aggregation needed)
SELECT * FROM sales_dashboard
WHERE day = CURRENT_DATE;

-- Refresh only the changes, for example every 5 minutes from cron
-- (automatic background refresh is planned)
REFRESH MATERIALIZED VIEW sales_dashboard INCREMENTALLY;

-- Check staleness
SELECT * FROM pg_mv_staleness()
WHERE view_name = 'sales_dashboard';

Learn More: See the Materialized Views Tutorial

Transparent Data Encryption

Protect sensitive data with AES-256-GCM encryption.

Example: Encrypted Database

[encryption]
enabled = true
key_source = { Environment = "HELIOSDB_ENCRYPTION_KEY" }

export HELIOSDB_ENCRYPTION_KEY="$(openssl rand -hex 32)"
export HELIOSDB_JWT_SECRET="$(openssl rand -hex 32)"
heliosdb-lite start --data-dir ./encrypted --config config.toml

-- All operations are transparently encrypted
CREATE TABLE secrets (id INT, data TEXT);
INSERT INTO secrets VALUES (1, 'Top secret information');
SELECT * FROM secrets;   -- decrypted on read; ciphertext on disk

Learn More: See the Encryption Tutorial

Next Steps

This tutorial covered the basics of HeliosDB-Lite.

Recommended Learning Path

Core Skills (Start here)
- Parameterized Queries - SQL injection protection
Advanced Features (Explore next)
- Vector Search Tutorial - Semantic search
- Encryption Tutorial - Data protection
- Materialized Views Tutorial - Analytics
- Time-Travel Tutorial - Historical queries
Production Deployment

Documentation

User Guides: Guides
SQL Reference: SQL Reference
CLI Reference: CLI Reference

Community and Support

Product page: www.heliosdb.com/lite.html
Issue Tracker: Report bugs
Discussions: Ask on Discord
Discord: https://discord.gg/yTykuUrFXc

Quick Reference Card

Common Commands:

-- Database operations
CREATE TABLE name (columns);
INSERT INTO table VALUES (...);
SELECT * FROM table WHERE condition;
UPDATE table SET col = val WHERE condition;
DELETE FROM table WHERE condition;

-- Advanced features
CREATE INDEX idx ON table USING hnsw (vector_col);
CREATE BRANCH branch FROM main;
CREATE MATERIALIZED VIEW mv AS SELECT ...;
SELECT * FROM table AS OF TIMESTAMP '...';

-- System introspection
\d                             -- List tables
\d table                       -- Describe table
SELECT * FROM pg_database_branches();
SELECT * FROM pg_mv_staleness();
SELECT * FROM pg_vector_index_stats();

Troubleshooting

Common Issues

Issue: cargo build fails with “linker not found” Solution: Install build tools:

# Linux
sudo apt-get install build-essential

# macOS
xcode-select --install

Issue: REPL shows “Permission denied” when creating database Solution: Check directory permissions:

chmod 755 /path/to/database/directory

Issue: Server mode shows “Address already in use” Solution: Port 5432 is already taken. Use a different port:

export HELIOSDB_JWT_SECRET="$(openssl rand -hex 32)"
heliosdb-lite start --data-dir ./mydb --port 5433

Issue: Vector queries are slow Solution: Create an HNSW index:

CREATE INDEX idx ON table USING hnsw (vector_col);

Getting Help

If you encounter issues:

Check troubleshooting guidance for documented limitations
Email support@heliosdb.com
Ask in Discord
Open a new issue with:
- HeliosDB-Lite version (\version in the REPL, or curl http://localhost:8080/version)
- Rust version (rustc --version)
- Operating system
- Minimal reproducible example

Appendix: Full Example Application

Here’s a complete example that demonstrates multiple features. Save it as app.sql and run it in the REPL (paste it into heliosdb-lite repl -d ./app) or with psql -f app.sql against a running server:

-- Schema
CREATE TABLE IF NOT EXISTS users (
    id SERIAL PRIMARY KEY,
    name TEXT NOT NULL,
    email TEXT NOT NULL UNIQUE,
    created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP
);

CREATE TABLE IF NOT EXISTS posts (
    id SERIAL PRIMARY KEY,
    user_id INT NOT NULL,
    title TEXT NOT NULL,
    content TEXT,
    embedding VECTOR(384),
    created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP
);

-- Indexes
CREATE INDEX IF NOT EXISTS idx_posts_user ON posts(user_id);
CREATE INDEX IF NOT EXISTS idx_posts_embedding ON posts
    USING hnsw (embedding vector_cosine_ops)
    WITH (m = 16, ef_construction = 200);

-- Data, in one transaction
BEGIN;
INSERT INTO users (name, email) VALUES ('Alice', 'alice@example.com');
INSERT INTO users (name, email) VALUES ('Bob', 'bob@example.com');
COMMIT;

-- Query with join
SELECT u.name, COUNT(p.id) AS post_count
FROM users u
LEFT JOIN posts p ON u.id = p.user_id
GROUP BY u.name;

-- Materialized view for analytics
CREATE MATERIALIZED VIEW IF NOT EXISTS user_stats AS
SELECT
    u.id,
    u.name,
    COUNT(p.id) AS total_posts,
    MAX(p.created_at) AS last_post_at
FROM users u
LEFT JOIN posts p ON u.id = p.user_id
GROUP BY u.id, u.name;

SELECT * FROM user_stats;

For more advanced topics, explore the documentation or try the tutorials.

Feedback: Report issues or suggest improvements