Skip to content
HeliosDB HeliosDB Lite

Quick Start Guide

Get up and running with HeliosDB-Lite in 5 minutes.

Create a Database

Server (any PostgreSQL driver)

Start the server, then connect with a standard PostgreSQL driver. Lite is not published on PyPI; from Python, use psycopg.

Terminal window
# Lite refuses to start without a REST token-signing secret
export HELIOSDB_JWT_SECRET="$(openssl rand -hex 32)"
heliosdb-lite start --data-dir ./mydb
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 1").fetchone())

The default --auth trust is for local development only; see Deployment Modes and the authentication guide before you expose the server.

CLI (REPL)

Terminal window
# Start REPL with file database
heliosdb-lite repl --data-dir ./mydb


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

Create Tables

-- Users table
CREATE TABLE users (
    id INTEGER PRIMARY KEY,
    name TEXT NOT NULL,
    email TEXT UNIQUE,
    created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP
);


-- Orders table with foreign key concept
CREATE TABLE orders (
    id INTEGER PRIMARY KEY,
    user_id INTEGER NOT NULL,
    total DECIMAL(10,2),
    status TEXT DEFAULT 'pending'
);

Insert Data

-- Single insert
INSERT INTO users (id, name, email) VALUES (1, 'Alice', 'alice@example.com');


-- Multiple rows
INSERT INTO users (id, name, email) VALUES
    (2, 'Bob', 'bob@example.com'),
    (3, 'Carol', 'carol@example.com');


-- Insert with RETURNING
INSERT INTO orders (user_id, total) VALUES (1, 99.99) RETURNING id;

Query Data

-- Basic query
SELECT * FROM users;


-- With conditions
SELECT name, email FROM users WHERE id > 1;


-- Join tables
SELECT u.name, o.total
FROM users u
JOIN orders o ON u.id = o.user_id;


-- Aggregation
SELECT user_id, SUM(total) as total_spent
FROM orders
GROUP BY user_id;

Try Advanced Features

Time-Travel Queries

-- Query data as it existed yesterday
SELECT * FROM orders AS OF TIMESTAMP '2025-01-14 00:00:00';

Database Branching

-- Create a development branch (AS OF is optional)
CREATE DATABASE BRANCH dev FROM main AS OF NOW;


-- Switch to branch
USE BRANCH dev;


-- Make changes safely
DELETE FROM users WHERE id = 1;


-- Switch back
USE BRANCH main;
-- Original data is still there!
-- Create table with vector column
CREATE TABLE documents (
    id INTEGER PRIMARY KEY,
    content TEXT,
    embedding VECTOR(384)
);


-- Insert with embedding
INSERT INTO documents (id, content, embedding)
VALUES (1, 'Machine learning basics', '[0.1, 0.2, ...]');


-- Similarity search
SELECT content FROM documents
ORDER BY embedding <-> '[0.15, 0.25, ...]'
LIMIT 5;

REPL Tips

Terminal window
# Show help
\h


# List tables
\d


# Describe table
\d users


# Show branches
\branches


# Toggle timing
\timing

Next Steps