---
title: "Getting Started with HeliosDB-Lite"
---

# Getting Started with HeliosDB-Lite

**Estimated Time**: 30 minutes

---

## Table of Contents

1. [Introduction](#introduction)
2. [Installation](#installation)
3. [Your First Database](#your-first-database)
4. [REPL vs Server Mode](#repl-vs-server-mode)
5. [Quick Feature Tour](#quick-feature-tour)
6. [Next Steps](#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](mailto: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)

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

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

# Verify installation
heliosdb-lite --help
```

### Option 3: Docker

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

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

```bash
heliosdb-lite repl --memory
```

**Output**:
```
HeliosDB-Lite
Type \h for help, \q to quit

heliosdb>
```

#### Create Your First Table

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

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

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

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

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

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

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

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

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

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

Once connected, use standard PostgreSQL commands:

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

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

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

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

```sql
-- 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](https://www.heliosdb.com/docs/lite/guides/tutorials/vector_search_tutorial/)

### Time-Travel Queries

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

#### Example: Audit Historical Changes

```sql
-- 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](/docs/lite/guides/tutorials/time_travel_tutorial/)

### Database Branching

Git-like branches for safe schema changes and testing.

#### Example: Test Schema Changes

```sql
-- 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](/docs/lite/guides/tutorials/database_branching_tutorial/)

### Materialized Views

Pre-compute expensive queries for instant dashboard performance.

#### Example: Real-Time Dashboard

```sql
-- 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](/docs/lite/guides/tutorials/materialized_views_tutorial/)

### Transparent Data Encryption

Protect sensitive data with AES-256-GCM encryption.

#### Example: Encrypted Database

```toml
# config.toml
[encryption]
enabled = true
key_source = { Environment = "HELIOSDB_ENCRYPTION_KEY" }
```

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

```sql
-- 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](/docs/lite/guides/tutorials/encryption_tutorial/)

---

## Next Steps

This tutorial covered the basics of HeliosDB-Lite.

### Recommended Learning Path

1. **Core Skills** (Start here)
   - [Parameterized Queries](/docs/lite/guides/parameterized_queries/) - SQL injection protection

2. **Advanced Features** (Explore next)
   - [Vector Search Tutorial](https://www.heliosdb.com/docs/lite/guides/tutorials/vector_search_tutorial/) - Semantic search
   - [Encryption Tutorial](https://www.heliosdb.com/docs/lite/guides/tutorials/encryption_tutorial/) - Data protection
   - [Materialized Views Tutorial](https://www.heliosdb.com/docs/lite/guides/tutorials/materialized_views_tutorial/) - Analytics
   - [Time-Travel Tutorial](https://www.heliosdb.com/docs/lite/guides/tutorials/time_travel_tutorial/) - Historical queries

3. **Production Deployment**

### Documentation

- **User Guides**: [Guides](/docs/lite/guides/)
- **SQL Reference**: [SQL Reference](/docs/lite/user-guide/sql-reference/)
- **CLI Reference**: [CLI Reference](/docs/lite/reference/cli/)

### Community and Support

- **Product page**: [www.heliosdb.com/lite.html](https://www.heliosdb.com/lite.html)
- **Issue Tracker**: [Report bugs](mailto:support@heliosdb.com)
- **Discussions**: [Ask on Discord](https://discord.gg/yTykuUrFXc)
- **Discord**: https://discord.gg/yTykuUrFXc

### Quick Reference Card

**Common Commands**:

```sql
-- 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:
```bash
# Linux
sudo apt-get install build-essential

# macOS
xcode-select --install
```

**Issue**: REPL shows "Permission denied" when creating database
**Solution**: Check directory permissions:
```bash
chmod 755 /path/to/database/directory
```

**Issue**: Server mode shows "Address already in use"
**Solution**: Port 5432 is already taken. Use a different port:
```bash
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:
```sql
CREATE INDEX idx ON table USING hnsw (vector_col);
```

### Getting Help

If you encounter issues:

1. Check troubleshooting guidance for documented limitations
2. Email [support@heliosdb.com](mailto:support@heliosdb.com)
3. Ask in [Discord](https://discord.gg/yTykuUrFXc)
4. 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:

```sql
-- 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](mailto:support@heliosdb.com)