Skip to content

Quick Start Guide

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

Create a Database

use heliosdb_lite::EmbeddedDatabase;

fn main() -> Result<(), Box<dyn std::error::Error>> {
    // File-based database
    let db = EmbeddedDatabase::new("./mydb")?;

    // Or in-memory
    let db = EmbeddedDatabase::new_in_memory()?;

    Ok(())
}

from heliosdb_lite import Client

# Connect to server
client = Client("http://localhost:8080")

# Or embedded
from heliosdb_lite import EmbeddedDatabase
db = EmbeddedDatabase("./mydb")

# Start REPL with file database
heliosdb-lite --repl ./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
CREATE DATABASE BRANCH dev FROM main;

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

# Show help
\h

# List tables
\d

# Describe table
\d users

# Show branches
\branches

# Toggle timing
\timing

Next Steps