HeliosDB Developer Quickstart

HeliosDB Developer Quickstart

From Zero to Production in 10 Minutes

This guide will have you building with HeliosDB in under 10 minutes. We’ll cover account creation, database setup, and your first queries.

---

Prerequisites

• A terminal/command line
• curl (or any HTTP client)
• Your favorite programming language

---

Step 1: Create Your Account (1 minute)

Option A: CLI (Recommended)

# Install the HeliosDB CLI
curl -fsSL https://get.heliosdb.io | sh

# Sign up
helios auth signup
# Follow the prompts for email verification

Option B: API

curl -X POST https://api.heliosdb.io/v1/auth/signup \
  -H "Content-Type: application/json" \
  -d '{
    "email": "your@email.com",
    "password": "your-secure-password"
  }'

Option C: Web Console

Visit console.heliosdb.io/signup

---

Step 2: Get Your API Token (30 seconds)

After signup, retrieve your Bearer token:

# CLI
helios auth login
helios auth token

# Or via API
curl -X POST https://api.heliosdb.io/v1/auth/login \
  -H "Content-Type: application/json" \
  -d '{
    "email": "your@email.com",
    "password": "your-secure-password"
  }'

Response:

{
  "token": "hdb_live_xxxxxxxxxxxxxxxxxxxx",
  "expires_at": "2025-12-16T00:00:00Z"
}

Save this token! You’ll use it for all API calls.

export HELIOS_TOKEN="hdb_live_xxxxxxxxxxxxxxxxxxxx"

---

Step 3: Create Your First Database (1 minute)

Using CLI

helios db create my-first-db --tier=free

Using API

curl -X POST https://api.heliosdb.io/v1/databases \
  -H "Authorization: Bearer $HELIOS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "my-first-db",
    "tier": "free",
    "region": "us-east-1"
  }'

Response:

{
  "id": "db_xxxxxxxxxxxx",
  "name": "my-first-db",
  "tier": "free",
  "status": "ready",
  "endpoints": {
    "postgresql": "my-first-db.heliosdb.io:5432",
    "mysql": "my-first-db.heliosdb.io:3306",
    "mongodb": "my-first-db.heliosdb.io:27017",
    "redis": "my-first-db.heliosdb.io:6379",
    "rest": "https://my-first-db.heliosdb.io/api/v1"
  }
}

---

Step 4: Connect and Query (2 minutes)

Option A: PostgreSQL

# Python with psycopg2
import psycopg2
import os

conn = psycopg2.connect(
    host="my-first-db.heliosdb.io",
    port=5432,
    database="main",
    user="default",
    password=os.environ["HELIOS_TOKEN"]
)

cursor = conn.cursor()
cursor.execute("SELECT version()")
print(cursor.fetchone())
# ('HeliosDB 7.0.0 (PostgreSQL 17 compatible)',)

Option B: MySQL

// Node.js with mysql2
const mysql = require('mysql2/promise');

const connection = await mysql.createConnection({
  host: 'my-first-db.heliosdb.io',
  port: 3306,
  user: 'default',
  password: process.env.HELIOS_TOKEN,
  database: 'main'
});

const [rows] = await connection.execute('SELECT VERSION()');
console.log(rows);
// [{ 'VERSION()': 'HeliosDB 7.0.0 (MySQL 8.0 compatible)' }]

Option C: MongoDB

// Node.js with MongoDB driver
const { MongoClient } = require('mongodb');

const client = new MongoClient(
  `mongodb://default:${process.env.HELIOS_TOKEN}@my-first-db.heliosdb.io:27017`
);

await client.connect();
const db = client.db('main');
const result = await db.command({ ping: 1 });
console.log(result);
// { ok: 1 }

Option D: REST API

# Create a table
curl -X POST https://my-first-db.heliosdb.io/api/v1/sql \
  -H "Authorization: Bearer $HELIOS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "CREATE TABLE users (id SERIAL PRIMARY KEY, name TEXT, email TEXT UNIQUE)"
  }'

# Insert data
curl -X POST https://my-first-db.heliosdb.io/api/v1/sql \
  -H "Authorization: Bearer $HELIOS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "INSERT INTO users (name, email) VALUES ($1, $2) RETURNING *",
    "params": ["Alice", "alice@example.com"]
  }'

# Query data
curl -X POST https://my-first-db.heliosdb.io/api/v1/sql \
  -H "Authorization: Bearer $HELIOS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "SELECT * FROM users WHERE name = $1",
    "params": ["Alice"]
  }'

---

Step 5: Use Database Branching (2 minutes)

One of HeliosDB’s killer features - instant database copies:

# Create a branch for development
curl -X POST https://my-first-db.heliosdb.io/api/v1/branches \
  -H "Authorization: Bearer $HELIOS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "feature/user-auth",
    "from": "main"
  }'
# Created in 555 microseconds!

-- Or via SQL
SELECT helios_create_branch('feature/user-auth', 'main');

Now you have a complete, isolated copy of your database. Make changes safely:

# Connect to the branch
curl -X POST https://my-first-db.heliosdb.io/api/v1/sql \
  -H "Authorization: Bearer $HELIOS_TOKEN" \
  -H "X-Helios-Branch: feature/user-auth" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "ALTER TABLE users ADD COLUMN password_hash TEXT"
  }'

When ready, merge back:

curl -X POST https://my-first-db.heliosdb.io/api/v1/branches/merge \
  -H "Authorization: Bearer $HELIOS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "source": "feature/user-auth",
    "target": "main"
  }'

---

Step 6: Add AI/Vector Capabilities (2 minutes)

Enable semantic search with built-in vector support:

-- Create a table with auto-generated embeddings
CREATE TABLE documents (
    id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
    title TEXT NOT NULL,
    content TEXT NOT NULL,
    embedding VECTOR(1536) GENERATED ALWAYS AS (
        helios_embed('openai/text-embedding-3-small', content)
    ) STORED
);

-- Insert a document (embedding auto-generated)
INSERT INTO documents (title, content) VALUES
    ('Getting Started', 'HeliosDB is a universal database platform...'),
    ('API Guide', 'The REST API supports all CRUD operations...'),
    ('Branching', 'Database branches enable isolated development...');

-- Semantic search
SELECT title, content,
       1 - (embedding <-> helios_embed('openai/text-embedding-3-small', 'how to use the API')) as similarity
FROM documents
ORDER BY similarity DESC
LIMIT 5;

---

Step 7: Generate APIs Automatically (1 minute)

HeliosDB can generate REST and GraphQL APIs from your schema:

# Generate REST API for your tables
curl -X POST https://my-first-db.heliosdb.io/api/v1/codegen/rest \
  -H "Authorization: Bearer $HELIOS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "tables": ["users", "documents"],
    "operations": ["create", "read", "update", "delete", "list"]
  }'

Response includes auto-generated endpoints:

{
  "endpoints": {
    "users": {
      "create": "POST /api/v1/users",
      "read": "GET /api/v1/users/:id",
      "update": "PUT /api/v1/users/:id",
      "delete": "DELETE /api/v1/users/:id",
      "list": "GET /api/v1/users"
    },
    "documents": {
      "create": "POST /api/v1/documents",
      "read": "GET /api/v1/documents/:id",
      "semantic_search": "POST /api/v1/documents/search"
    }
  }
}

---

Common Patterns

Pattern 1: User Authentication

-- Create users table
CREATE TABLE users (
    id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
    email TEXT UNIQUE NOT NULL,
    password_hash TEXT NOT NULL,
    created_at TIMESTAMPTZ DEFAULT NOW()
);

-- Create sessions table
CREATE TABLE sessions (
    id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
    user_id UUID REFERENCES users(id) ON DELETE CASCADE,
    token TEXT UNIQUE NOT NULL,
    expires_at TIMESTAMPTZ NOT NULL,
    created_at TIMESTAMPTZ DEFAULT NOW()
);

-- Register user
INSERT INTO users (email, password_hash)
VALUES ($1, crypt($2, gen_salt('bf')))
RETURNING id, email;

-- Login (verify password)
SELECT id, email FROM users
WHERE email = $1 AND password_hash = crypt($2, password_hash);

-- Create session
INSERT INTO sessions (user_id, token, expires_at)
VALUES ($1, encode(gen_random_bytes(32), 'hex'), NOW() + INTERVAL '7 days')
RETURNING token;

Pattern 2: E-Commerce Orders

-- Products with vector search
CREATE TABLE products (
    id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
    name TEXT NOT NULL,
    description TEXT,
    price DECIMAL(10,2) NOT NULL,
    embedding VECTOR(1536) GENERATED ALWAYS AS (
        helios_embed('openai/text-embedding-3-small', name || ' ' || COALESCE(description, ''))
    ) STORED
);

-- Orders with status tracking
CREATE TABLE orders (
    id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
    user_id UUID REFERENCES users(id),
    status TEXT DEFAULT 'pending',
    total DECIMAL(10,2) NOT NULL,
    created_at TIMESTAMPTZ DEFAULT NOW()
);

-- Order items
CREATE TABLE order_items (
    id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
    order_id UUID REFERENCES orders(id) ON DELETE CASCADE,
    product_id UUID REFERENCES products(id),
    quantity INTEGER NOT NULL,
    price DECIMAL(10,2) NOT NULL
);

-- Find similar products
SELECT name, price,
       1 - (embedding <-> helios_embed('openai/text-embedding-3-small', 'comfortable running shoes')) as relevance
FROM products
ORDER BY relevance DESC
LIMIT 10;

Pattern 3: Real-Time Analytics

-- Events table with time-series optimization
CREATE TABLE events (
    id UUID DEFAULT gen_random_uuid(),
    event_type TEXT NOT NULL,
    user_id UUID,
    properties JSONB,
    timestamp TIMESTAMPTZ DEFAULT NOW(),
    PRIMARY KEY (timestamp, id)
) PARTITION BY RANGE (timestamp);

-- Create monthly partitions
SELECT helios_create_time_partitions('events', 'month', 12);

-- Query recent events
SELECT event_type,
       COUNT(*) as count,
       COUNT(DISTINCT user_id) as unique_users
FROM events
WHERE timestamp > NOW() - INTERVAL '1 hour'
GROUP BY event_type
ORDER BY count DESC;

-- Real-time aggregation (materialized view)
CREATE MATERIALIZED VIEW event_stats
WITH (timescaledb.continuous) AS
SELECT
    time_bucket('1 minute', timestamp) as minute,
    event_type,
    COUNT(*) as count
FROM events
GROUP BY minute, event_type;

---

Next Steps

Learn More

• API Reference - Complete API documentation
• AI Integration Guide - Build AI applications
• Authentication Guide - Security best practices

Join the Community

• Discord - Real-time help
• GitHub - Source code
• Forum - Discussions

Get Help

• Documentation
• Support
• Status Page

---

Quick Reference

CLI Commands

helios auth login           # Authenticate
helios db create NAME       # Create database
helios db list              # List databases
helios db connect NAME      # Connect to database
helios branch create NAME   # Create branch
helios branch list          # List branches
helios sql "QUERY"          # Execute SQL

Environment Variables

export HELIOS_TOKEN="hdb_live_xxx"  # API token
export HELIOS_DB="my-db"            # Default database
export HELIOS_BRANCH="main"         # Default branch

Connection Strings

PostgreSQL: postgresql://default:TOKEN@DB.heliosdb.io:5432/main
MySQL:      mysql://default:TOKEN@DB.heliosdb.io:3306/main
MongoDB:    mongodb://default:TOKEN@DB.heliosdb.io:27017/main
Redis:      redis://default:TOKEN@DB.heliosdb.io:6379
REST:       https://DB.heliosdb.io/api/v1

---

You’re ready to build! Need help? Join our Discord.