Quick Start Guide

Quick Start Guide

Get HeliosDB Nano running in 5 minutes

---

Choose Your Mode

HeliosDB Nano runs in three modes:

Mode	Best For	Latency	Setup
Embedded	Single-app, edge, mobile	Microseconds	3 lines
Server	Multi-client, team use	Milliseconds	1 command
REPL	Exploration, prototyping	Interactive	1 command

---

Option 1: Server Mode (REST API)

Step 1: Start the Server

# Download (Linux/macOS)
curl -L https://github.com/heliosdb/heliosdb/releases/latest/download/heliosdb-nano -o heliosdb-nano
chmod +x heliosdb-nano

# Start server
./heliosdb-nano --mode server --port 6543 --data-dir ./data

Output:

HeliosDB Nano v3.3.0
Server listening on 0.0.0.0:6543
REST API: http://localhost:6543/api/v1
PostgreSQL Wire: postgresql://localhost:6543

Step 2: Get Your API Token

# Login to get Bearer token
curl -X POST http://localhost:6543/auth/v1/token \
  -H "Content-Type: application/json" \
  -d '{
    "email": "admin@example.com",
    "password": "admin"
  }'

Response:

{
  "access_token": "eyJhbGciOiJIUzI1NiIs...",
  "token_type": "bearer",
  "expires_in": 3600,
  "refresh_token": "dGhpcyBpcyBhIHJlZnJl..."
}

Step 3: Create Your First Table

export TOKEN="eyJhbGciOiJIUzI1NiIs..."

# Create table via SQL
curl -X POST http://localhost:6543/api/v1/query \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "sql": "CREATE TABLE users (id SERIAL PRIMARY KEY, name TEXT, email TEXT UNIQUE)"
  }'

Step 4: Insert Data

# Insert via REST API
curl -X POST http://localhost:6543/rest/v1/users \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"name": "Alice", "email": "alice@example.com"}'

Step 5: Query Data

# Query via SQL
curl -X POST http://localhost:6543/api/v1/query \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"sql": "SELECT * FROM users"}'

# Or via REST (Supabase-compatible)
curl "http://localhost:6543/rest/v1/users?select=*" \
  -H "Authorization: Bearer $TOKEN"

---

Option 2: Embedded Mode (Rust)

Step 1: Add Dependency

Cargo.toml

[dependencies]
heliosdb-nano = "3.3"

Step 2: Open Database

use heliosdb_nano::EmbeddedDatabase;

fn main() -> Result<(), Box<dyn std::error::Error>> {
    // Open or create database
    let db = EmbeddedDatabase::open("./my_app.db")?;

    // Create table
    db.execute("CREATE TABLE IF NOT EXISTS users (
        id INTEGER PRIMARY KEY,
        name TEXT NOT NULL,
        email TEXT UNIQUE
    )")?;

    // Insert data
    db.execute("INSERT INTO users (name, email) VALUES ('Alice', 'alice@example.com')")?;

    // Query data
    let results = db.query("SELECT * FROM users WHERE name = 'Alice'")?;
    for row in results {
        println!("{:?}", row);
    }

    Ok(())
}

Step 3: Use Vector Search

// Create table with vector column
db.execute("CREATE TABLE documents (
    id SERIAL PRIMARY KEY,
    content TEXT,
    embedding VECTOR(384)
)")?;

// Insert with embedding
let embedding = vec![0.1, 0.2, 0.3, /* ... 384 dimensions */];
db.execute_with_params(
    "INSERT INTO documents (content, embedding) VALUES ($1, $2)",
    &[&"Hello world", &embedding]
)?;

// Similarity search
let query_vector = vec![0.15, 0.25, 0.35, /* ... */];
let results = db.query_with_params(
    "SELECT content, embedding <-> $1 AS distance
     FROM documents
     ORDER BY embedding <-> $1
     LIMIT 5",
    &[&query_vector]
)?;

---

Option 3: REPL Mode (Interactive)

Start REPL

./heliosdb-nano --mode repl --data-dir ./data

Interactive Session

HeliosDB> CREATE TABLE products (
    id SERIAL PRIMARY KEY,
    name TEXT,
    price DECIMAL(10,2),
    embedding VECTOR(3)
);
Table 'products' created

HeliosDB> INSERT INTO products (name, price, embedding)
          VALUES ('Widget', 29.99, '[0.1, 0.2, 0.3]');
1 row inserted

HeliosDB> INSERT INTO products (name, price, embedding)
          VALUES ('Gadget', 49.99, '[0.4, 0.5, 0.6]');
1 row inserted

HeliosDB> SELECT * FROM products;
╭────┬────────┬───────┬─────────────────╮
│ id │  name  │ price │    embedding    │
├────┼────────┼───────┼─────────────────┤
│  1 │ Widget │ 29.99 │ [0.1, 0.2, 0.3] │
│  2 │ Gadget │ 49.99 │ [0.4, 0.5, 0.6] │
╰────┴────────┴───────┴─────────────────╯

HeliosDB> SELECT name, embedding <-> '[0.2, 0.3, 0.4]' AS distance
          FROM products
          ORDER BY distance
          LIMIT 1;
╭────────┬──────────╮
│  name  │ distance │
├────────┼──────────┤
│ Widget │   0.173  │
╰────────┴──────────╯

---

Using with Common Languages

Python

import requests

BASE_URL = "http://localhost:6543"
TOKEN = "your-bearer-token"

headers = {
    "Authorization": f"Bearer {TOKEN}",
    "Content-Type": "application/json"
}

# Execute SQL
response = requests.post(
    f"{BASE_URL}/api/v1/query",
    headers=headers,
    json={"sql": "SELECT * FROM users"}
)
print(response.json())

JavaScript/TypeScript

const BASE_URL = "http://localhost:6543";
const TOKEN = "your-bearer-token";

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

// Usage
const users = await query("SELECT * FROM users LIMIT 10");
console.log(users);

Go

package main

import (
    "bytes"
    "encoding/json"
    "net/http"
)

func query(sql string) (map[string]interface{}, error) {
    payload, _ := json.Marshal(map[string]string{"sql": sql})

    req, _ := http.NewRequest("POST", "http://localhost:6543/api/v1/query", bytes.NewBuffer(payload))
    req.Header.Set("Authorization", "Bearer "+token)
    req.Header.Set("Content-Type", "application/json")

    client := &http.Client{}
    resp, err := client.Do(req)
    if err != nil {
        return nil, err
    }
    defer resp.Body.Close()

    var result map[string]interface{}
    json.NewDecoder(resp.Body).Decode(&result)
    return result, nil
}

PostgreSQL Drivers

# Connect with any PostgreSQL client
psql -h localhost -p 6543 -U admin -d helios

# Or use connection string
DATABASE_URL="postgres://admin:password@localhost:6543/helios"

---

Next Steps

Guide	Description
Authentication	Bearer tokens and API keys
Schema Generation	Auto-generate DDL from JSON
Vector Search	HNSW and similarity queries
Multi-Tenancy	RLS and tenant isolation

---

Common Commands Reference

Server Management

# Start with encryption
./heliosdb-nano --mode server --encryption-key YOUR_KEY

# Start with TLS
./heliosdb-nano --mode server --tls-cert cert.pem --tls-key key.pem

# View logs
./heliosdb-nano --mode server --log-level debug

Database Operations

-- Create branch for testing
CREATE BRANCH test_feature FROM main;
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 if server is running
ps aux | grep heliosdb

# Check port availability
lsof -i :6543

Authentication Failed

# Verify token is valid
curl http://localhost:6543/api/v1/health \
  -H "Authorization: Bearer $TOKEN"

Permission Denied

# Check file permissions
ls -la ./data

# Ensure write access
chmod 755 ./data

---

Need help? Join Discord | File Issue