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

# Getting Started with HeliosDB Lite

This guide installs HeliosDB Lite and runs a first session.

## Table of Contents

- [Installation](#installation)
- [Quick Start](#quick-start)
- [Usage Modes](#usage-modes)
- [Common Use Cases](#common-use-cases)
- [Configuration](#configuration)
- [Next Steps](#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](mailto:sales@heliosdb.com) for access to the source distribution.
It is not published on crates.io, Docker Hub or Homebrew.

### Option 1: Cargo (Recommended)

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

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

### Option 2: Docker

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

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

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

```bash
# 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](/docs/lite/guides/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

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

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

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

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

```bash
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](/docs/lite/guides/deployment_modes/).

## Common Use Cases

### Use Case 1: Web Application (Python + psycopg2)

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

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

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

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

```bash
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](/docs/lite/guides/encryption_quickstart/).

## Configuration

### Basic Configuration

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

```toml
[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](/docs/lite/user-guide/configuration/) and the
[CLI Reference](/docs/lite/reference/cli/).

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

```sql
SELECT * FROM large_table LIMIT 100 OFFSET 0;
```

### Issue: "Permission denied"

**Cause**: Insufficient file system permissions.

**Solution**: Check directory permissions:

```bash
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](/docs/lite/user-guide/sql-reference/)** - Complete SQL syntax guide
- **[REST API Tutorial](/docs/lite/guides/tutorials/rest_api_tutorial/)** - HTTP access

### ORM Integration

- **SQLAlchemy** (Python), **Diesel** (Rust), **Prisma** (TypeScript): see
  [ORM Support](/docs/lite/features/orm_support/)

### Community & Support

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

## Quick Reference

### SQL Commands

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