Getting Started with HeliosDB Lite

This guide installs HeliosDB Lite and runs a first session.

Table of Contents

• Installation
• Quick Start
• Usage Modes
• Common Use Cases
• Configuration
• Next Steps

Installation

Prerequisites

• Rust 1.75+ (for building from source)
• Operating System: Linux, macOS, or Windows

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

Option 1: Cargo (Recommended)

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

# Or build in place
cd heliosdb-lite
cargo build --release

Option 2: Docker

# Build the image inside the unpacked source distribution
cd heliosdb-lite
docker build -f deployment/docker/Dockerfile -t heliosdb-lite:latest .
docker run -it --rm -e HELIOSDB_JWT_SECRET="$(openssl rand -hex 32)" heliosdb-lite:latest

Quick Start

1. Interactive REPL (Fastest Way to Try)

# Start in-memory database; add --dump-on-shutdown to dump on exit
heliosdb-lite repl --memory

# Or with persistent storage
heliosdb-lite repl -d ./mydb

Example session:

heliosdb> CREATE TABLE users (
  id SERIAL PRIMARY KEY,
  name TEXT NOT NULL,
  email TEXT UNIQUE,
  created_at TIMESTAMP DEFAULT NOW()
);
Query OK (0.002s)

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

heliosdb> SELECT * FROM users;
+----+-------+-------------------+-------------------------+
| id | name  | email             | created_at              |
+----+-------+-------------------+-------------------------+
| 1  | Alice | alice@example.com | 2025-11-15 13:00:00.000 |
| 2  | Bob   | bob@example.com   | 2025-11-15 13:00:00.001 |
+----+-------+-------------------+-------------------------+
(2 rows) (0.001s)

heliosdb> \d users  -- Describe table
heliosdb> \dt       -- List all tables
heliosdb> \?        -- Show help
heliosdb> \q        -- Quit

2. Server Mode (PostgreSQL-Compatible)

Start HeliosDB Lite as a PostgreSQL-compatible server:

# Signing secret for the REST API (the server refuses to start without it)
export HELIOSDB_JWT_SECRET="$(openssl rand -hex 32)"

# Start server
heliosdb-lite start --data-dir ./mydb --port 5432

# In another terminal, connect with psql
psql "postgresql://postgres@127.0.0.1:5432/heliosdb"

The server also serves the REST API on port 8080. Now you can use any PostgreSQL-compatible tool:

• psql (command-line client)
• pgAdmin (GUI)
• DBeaver (universal database tool)
• SQLAlchemy (Python ORM)
• Prisma (TypeScript ORM)
• Diesel (Rust ORM)

The default --auth trust accepts every connection and is for local development only. For anything reachable from another host, see Security Hardening.

Usage Modes

Mode 1: In-Memory (Fast, No Persistence)

Perfect for:

• Testing and CI/CD pipelines
• Temporary data processing
• Fast analytics on ephemeral data

export HELIOSDB_JWT_SECRET="$(openssl rand -hex 32)"
# CLI REPL
heliosdb-lite repl --memory
# CLI REPL with a graceful-exit dump
heliosdb-lite repl --memory --dump-on-shutdown --dump-file ./session.heliodump
# In-memory server
heliosdb-lite start --memory

Pros: Extremely fast, no disk I/O overhead Cons: Data is RAM-only unless you enable a shutdown dump with --dump-on-shutdown

Mode 2: Embedded REPL (In-Process, Persistent)

heliosdb-lite repl -d ./mydb

Pros: SQLite-like simplicity, zero configuration Cons: Single-process access only

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

Mode 3: Server (Network, Persistent)

Perfect for:

• Web applications
• Microservices
• Multi-client scenarios
• PostgreSQL migration

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

Pros: Multi-client access, PostgreSQL wire protocol and REST API Cons: Network overhead

Mode 4: Server with a Larger Cache (recommended for production)

heliosdb.toml

[storage]
cache_size = 536870912         # 512 MB memory cache
compression = "Zstd"           # "None", "Zstd" or "Lz4"

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

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

Adjust cache_size to the available RAM (for example 1 GB on 8 GB systems, 2 GB on 16 GB systems).

Quick Mode Selection:

Need	Use Mode
Testing, CI/CD	In-Memory
Local tools, single-process	Embedded REPL
Multi-client, basic server	Server
Production, high performance	Server with a larger cache

For detailed comparison and architecture, see Deployment Modes.

Common Use Cases

Use Case 1: Web Application (Python + psycopg2)

import psycopg2

conn = psycopg2.connect(host="127.0.0.1", port=5432, user="postgres", dbname="heliosdb")
with conn, conn.cursor() as cur:
    cur.execute("SELECT id, name FROM users WHERE email = %s", ("alice@example.com",))
    print(cur.fetchone())

Any PostgreSQL driver works the same way: Node.js pg, Go pgx, Java JDBC, Rust tokio-postgres or sqlx.

Use Case 2: AI/ML with Vector Search

-- Table with a vector column
CREATE TABLE documents (
    id SERIAL PRIMARY KEY,
    content TEXT,
    embedding VECTOR(1536)  -- OpenAI ada-002 dimension
);

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

-- Insert a document with its embedding (bind the vector as a parameter)
INSERT INTO documents (content, embedding) VALUES ('HeliosDB is fast', $1);

-- Semantic search (k-NN)
SELECT id, content, embedding <=> $1 AS distance
FROM documents
ORDER BY distance
LIMIT 10;

Use Case 3: Analytics with JSONB

CREATE TABLE events (
    id SERIAL PRIMARY KEY,
    event_type TEXT,
    metadata JSONB,
    created_at TIMESTAMP DEFAULT NOW()
);

INSERT INTO events (event_type, metadata) VALUES
    ('page_view', '{"page": "/home", "user_agent": "Mozilla/5.0"}'),
    ('purchase',  '{"amount": 99.99, "currency": "USD", "items": [1, 2, 3]}');

SELECT event_type, metadata->>'page' AS page
FROM events
WHERE metadata->>'currency' = 'USD';

Use Case 4: Encrypted Storage

heliosdb.toml

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

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

All data written by the server is encrypted at rest with AES-256-GCM. See the Encryption Quick Start.

Configuration

Basic Configuration

Create heliosdb.toml and pass it with --config:

[storage]
cache_size = 536870912  # 512 MB
compression = "Zstd"

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

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

See the Configuration reference and the CLI Reference.

Troubleshooting

Issue: “Database locked”

Cause: Another process is using the data directory.

Solution: Only one process opens a data directory at a time. Use server mode for multi-client access.

Issue: “Out of memory”

Cause: Large query result set.

Solution: Use LIMIT/OFFSET for pagination:

SELECT * FROM large_table LIMIT 100 OFFSET 0;

Issue: “Permission denied”

Cause: Insufficient file system permissions.

Solution: Check directory permissions:

chmod 755 ./heliosdb-data

Issue: Query performance slow

Solutions:

1. Add indexes: CREATE INDEX idx_name ON table (column);
2. Use EXPLAIN: EXPLAIN SELECT * FROM table WHERE...;
3. Increase cache: Set cache_size to a larger value

Next Steps

Learn More

• SQL Reference - Complete SQL syntax guide
• REST API Tutorial - HTTP access

ORM Integration

• SQLAlchemy (Python), Diesel (Rust), Prisma (TypeScript): see ORM Support

Community & Support

• Support: support@heliosdb.com
• Discord: https://discord.gg/yTykuUrFXc

Quick Reference

SQL Commands

-- Tables
CREATE TABLE name (col TYPE, ...);
DROP TABLE name;
ALTER TABLE name ADD COLUMN col TYPE;

-- Data
INSERT INTO table VALUES (...);
UPDATE table SET col = val WHERE ...;
DELETE FROM table WHERE ...;
SELECT * FROM table WHERE ... ORDER BY ... LIMIT 10;

-- Indexes
CREATE INDEX idx_name ON table (column);
CREATE INDEX idx_vector ON table USING hnsw (embedding vector_cosine_ops);

-- Transactions
BEGIN;
COMMIT;
ROLLBACK;

REPL Meta-Commands

\d [table]      Describe table (or list all tables if no arg)
\dt             List all tables
\di             List all indexes
\?              Show help
\h [command]    Show SQL command help
\q              Quit