Quick Start Guide

Get HeliosDB-Lite running in 5 minutes

---

Choose Your Mode

HeliosDB-Lite runs in three modes:

Mode	Best For	Latency	Setup
Embedded	Single-app, edge, mobile	In-process	Licensed source distribution
Server	Multi-client, team use	Network round trip	1 command
REPL	Exploration, prototyping	Interactive	1 command

In server mode, HeliosDB Lite serves the PostgreSQL wire protocol and a REST API. An MCP server, an Oracle listener, a MySQL listener and a gRPC query API are planned.

---

Option 1: Server Mode

Step 1: Build and Start the Server

# Build the binary from the licensed source distribution (no binary downloads;
# contact sales@heliosdb.com for access)
cd heliosdb-lite && cargo build --release && cp target/release/heliosdb-lite .. && cd ..

# PostgreSQL wire on 127.0.0.1:5432, REST API on 127.0.0.1:8080
export HELIOSDB_JWT_SECRET="$(openssl rand -hex 32)"   # required to start the server (REST token signing)
./heliosdb-lite start --data-dir ./data

The server prints its PostgreSQL and REST addresses when it is ready. Use --port, --http-port and --listen to change the ports or the bind address. For anything beyond local development, add --auth scram-sha-256 --password <password>; see Authentication.

Step 2: Create a Table over PostgreSQL Wire

Any PostgreSQL client or driver works:

psql -h 127.0.0.1 -p 5432 -U postgres -d heliosdb

CREATE TABLE users (id INTEGER PRIMARY KEY, name TEXT, email TEXT UNIQUE);
INSERT INTO users VALUES (1, 'Alice', 'alice@example.com');

Step 3: Get a REST Token

The REST API accepts HS256 JWTs signed with HELIOSDB_JWT_SECRET. Lite does not issue tokens itself, so mint one as shown in Authentication and export it:

export TOKEN="eyJhbGciOiJIUzI1NiIs..."

Step 4: Run SQL over REST

Statements that change data or schema go to execute, and queries go to query. Both take a branch name (main by default):

# Insert
curl -X POST http://127.0.0.1:8080/v1/branches/main/execute \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"sql": "INSERT INTO users VALUES (2, '\''Bob'\'', '\''bob@example.com'\'')"}'

# Query with a parameter
curl -X POST http://127.0.0.1:8080/v1/branches/main/query \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"sql": "SELECT * FROM users WHERE id = $1", "params": [{"type": "int4", "value": 1}]}'

A query returns columns, column_types, rows (one object per row), row_count and execution_time_ms.

---

Option 2: Embedded Mode

The engine can run inside your own process with no server, reading a local data directory. Embedding Lite in your application is covered by the licensed source distribution; the REPL below runs the same embedded engine interactively.

---

Option 3: REPL Mode (Interactive)

Start REPL

./heliosdb-lite repl --data-dir ./data

# Or in memory
./heliosdb-lite repl --memory

Interactive Session

CREATE TABLE products (
    id INTEGER PRIMARY KEY,
    name TEXT,
    price DECIMAL(10,2),
    embedding VECTOR(3)
);

INSERT INTO products VALUES (1, 'Widget', 29.99, '[0.1, 0.2, 0.3]');
INSERT INTO products VALUES (2, 'Gadget', 49.99, '[0.4, 0.5, 0.6]');

SELECT name, embedding <-> '[0.2, 0.3, 0.4]' AS distance
FROM products
ORDER BY distance
LIMIT 1;

---

Using with Common Languages

Over the PostgreSQL wire, use your language’s standard PostgreSQL driver. Over REST, any HTTP client works.

Python (PostgreSQL wire)

import psycopg  # pip install "psycopg[binary]"

with psycopg.connect("host=127.0.0.1 port=5432 user=postgres dbname=heliosdb") as conn:
    print(conn.execute("SELECT * FROM users").fetchall())

Python (REST)

import requests

BASE_URL = "http://127.0.0.1:8080/v1"
headers = {"Authorization": f"Bearer {TOKEN}"}

response = requests.post(
    f"{BASE_URL}/branches/main/query",
    headers=headers,
    json={"sql": "SELECT * FROM users"},
)
print(response.json()["rows"])

JavaScript/TypeScript (REST)

const BASE_URL = "http://127.0.0.1:8080/v1";

async function query(sql: string, token: string) {
  const response = await fetch(`${BASE_URL}/branches/main/query`, {
    method: "POST",
    headers: {
      "Authorization": `Bearer ${token}`,
      "Content-Type": "application/json"
    },
    body: JSON.stringify({ sql })
  });
  return response.json();
}

Go (PostgreSQL wire)

import "github.com/jackc/pgx/v5"

conn, err := pgx.Connect(ctx, "postgres://postgres@127.0.0.1:5432/heliosdb")

---

Next Steps

Guide	Description
Authentication	Wire authentication and REST tokens
Schema Generation	Draft DDL from JSON samples
Vector Search	HNSW and similarity queries
Multi-Tenancy	RLS and tenant isolation

---

Common Commands Reference

Server Management

# Every `start` needs the REST token-signing secret
export HELIOSDB_JWT_SECRET="$(openssl rand -hex 32)"

# Password authentication on the PostgreSQL wire
./heliosdb-lite start --data-dir ./data --auth scram-sha-256 --password "$DB_PASSWORD"

# TLS on the PostgreSQL wire
./heliosdb-lite start --data-dir ./data --tls-cert cert.pem --tls-key key.pem

# Run in the background, then check and stop it
./heliosdb-lite start --data-dir ./data --daemon
./heliosdb-lite status
./heliosdb-lite stop

Encryption at rest is configured in the [encryption] section of the configuration file passed with --config; see the Encryption Quick Start.

Database Operations

-- Create a branch for testing
CREATE DATABASE BRANCH test_feature FROM main AS OF NOW;
USE BRANCH test_feature;

-- Time travel query
SELECT * FROM orders AS OF TIMESTAMP '2024-01-01 00:00:00';

-- Create materialized view
CREATE MATERIALIZED VIEW monthly_sales AS
SELECT month, SUM(amount) FROM orders GROUP BY month;

---

Troubleshooting

Connection Refused

# Check a server started with --daemon
./heliosdb-lite status

# Check which process holds the ports
lsof -i :5432 -i :8080

The server binds to 127.0.0.1 by default. Use --listen 0.0.0.0 to accept remote connections, and enable password authentication when you do.

Authentication Failed

# The health endpoint needs no token; a 200 here means the REST API is up
curl http://127.0.0.1:8080/health

If /health answers but /v1/... returns 401, re-mint the token; see Authentication.

Permission Denied

# Check file permissions on the data directory
ls -la ./data

---

Need help? Join Discord | Email support