Getting Started with HeliosDB v6.0

Welcome to HeliosDB v6.0! This guide will get you up and running with polyglot WASM stored procedures and event-driven edge functions in under 30 minutes.

Quick Start (5 Minutes)

Step 1: Install HeliosDB

Option A: Docker (Easiest)

docker pull heliosdb/heliosdb:v6.0.0
docker run -d --name heliosdb -p 5432:5432 heliosdb/heliosdb:v6.0.0

Option B: Binary

wget https://github.com/heliosdb/heliosdb/releases/download/v6.0.0/heliosdb-v6.0.0-linux-x86_64.tar.gz
tar -xzf heliosdb-v6.0.0-linux-x86_64.tar.gz
./heliosdb/heliosdb &

Step 2: Verify Installation

# Check version
heliosdb-cli query "SELECT version()"
# Output: HeliosDB v6.0.0 (Polyglot Edge)

Step 3: Create Your First Database

heliosdb-cli query "CREATE DATABASE my_app"
heliosdb-cli query "\\c my_app"
heliosdb-cli query "CREATE TABLE users (id SERIAL PRIMARY KEY, name TEXT, email TEXT)"

Step 4: Write Your First WASM Function (Python)

Create function file:

from heliosdb import heliosdb_function, query

@heliosdb_function
def get_user_count() -> int:
    result = query("SELECT COUNT(*) FROM users")
    return result.fetchone()[0]

Deploy:

# Compile to WASM
heliosdb-sdk-python build hello.py --output hello.wasm

# Deploy
heliosdb-cli wasm deploy hello.wasm --name hello

# Call from SQL
heliosdb-cli query "SELECT get_user_count()"
# Output: 0

Success! You’ve deployed your first WASM function! 🎉

Python SDK Tutorial (15 Minutes)

Installation

pip install heliosdb-sdk-python

Example 1: Basic CRUD Operations

from heliosdb import heliosdb_function, query, execute

@heliosdb_function
def create_user(name: str, email: str) -> int:
    """Create a new user and return the ID"""
    result = execute(
        "INSERT INTO users (name, email) VALUES (?, ?) RETURNING id",
        [name, email]
    )
    return result.fetchone()[0]

@heliosdb_function
def get_user(user_id: int) -> dict:
    """Get user by ID"""
    result = query(
        "SELECT id, name, email FROM users WHERE id = ?",
        [user_id]
    )
    row = result.fetchone()
    if row:
        return {"id": row[0], "name": row[1], "email": row[2]}
    return None

@heliosdb_function
def update_user(user_id: int, name: str, email: str) -> bool:
    """Update user"""
    result = execute(
        "UPDATE users SET name = ?, email = ? WHERE id = ?",
        [name, email, user_id]
    )
    return result.rows_affected() > 0

@heliosdb_function
def delete_user(user_id: int) -> bool:
    """Delete user"""
    result = execute("DELETE FROM users WHERE id = ?", [user_id])
    return result.rows_affected() > 0

Deploy and test:

heliosdb-sdk-python build user_service.py
heliosdb-cli wasm deploy user_service.wasm

# Test
heliosdb-cli query "SELECT create_user('Alice', 'alice@example.com')"  # Returns: 1
heliosdb-cli query "SELECT get_user(1)"  # Returns: {"id": 1, "name": "Alice", ...}

Example 2: Transactions

from heliosdb import heliosdb_function, transaction, execute

@heliosdb_function
def transfer_money(from_account: int, to_account: int, amount: float) -> dict:
    """Transfer money between accounts (atomic)"""
    with transaction():
        # Debit from source
        execute("UPDATE accounts SET balance = balance - ? WHERE id = ?", [amount, from_account])

        # Credit to destination
        execute("UPDATE accounts SET balance = balance + ? WHERE id = ?", [amount, to_account])

        # Log transaction
        execute("INSERT INTO transfers (from_id, to_id, amount) VALUES (?, ?, ?)",
                [from_account, to_account, amount])

    return {"status": "success", "amount": amount}

Example 3: Complex Business Logic

from heliosdb import heliosdb_function, query, execute
import json

@heliosdb_function
def calculate_order_total(order_id: int) -> dict:
    """Calculate order total with discounts"""

    # Get order items
    items = query(
        "SELECT product_id, quantity, price FROM order_items WHERE order_id = ?",
        [order_id]
    ).fetchall()

    subtotal = sum(item[1] * item[2] for item in items)  # quantity * price

    # Calculate discount
    discount = 0
    if subtotal > 100:
        discount = subtotal * 0.10  # 10% off
    elif subtotal > 50:
        discount = subtotal * 0.05  # 5% off

    # Calculate tax
    tax = (subtotal - discount) * 0.08  # 8% tax

    total = subtotal - discount + tax

    # Update order
    execute("""
        UPDATE orders
        SET subtotal = ?, discount = ?, tax = ?, total = ?, updated_at = NOW()
        WHERE id = ?
    """, [subtotal, discount, tax, total, order_id])

    return {
        "subtotal": subtotal,
        "discount": discount,
        "tax": tax,
        "total": total
    }

Example 4: External API Calls

from heliosdb import heliosdb_function, execute
import requests  # Available in WASM runtime

@heliosdb_function
def geocode_address(address_id: int) -> dict:
    """Geocode address using external API"""

    # Get address from database
    address = query(
        "SELECT street, city, state, zip FROM addresses WHERE id = ?",
        [address_id]
    ).fetchone()

    # Call geocoding API
    response = requests.get(
        "https://api.geocoding.com/v1/geocode",
        params={
            "address": f"{address[0]}, {address[1]}, {address[2]} {address[3]}"
        }
    )

    data = response.json()
    lat, lng = data['latitude'], data['longitude']

    # Update address with coordinates
    execute(
        "UPDATE addresses SET latitude = ?, longitude = ? WHERE id = ?",
        [lat, lng, address_id]
    )

    return {"latitude": lat, "longitude": lng}

Example 5: Async Functions

from heliosdb import heliosdb_function, query
import asyncio

@heliosdb_function
async def get_user_with_orders(user_id: int) -> dict:
    """Get user and their orders (async)"""

    # Fetch user and orders in parallel
    user_task = asyncio.create_task(
        query("SELECT id, name, email FROM users WHERE id = ?", [user_id]).fetchone_async()
    )

    orders_task = asyncio.create_task(
        query("SELECT id, total, status FROM orders WHERE user_id = ?", [user_id]).fetchall_async()
    )

    user, orders = await asyncio.gather(user_task, orders_task)

    return {
        "user": {"id": user[0], "name": user[1], "email": user[2]},
        "orders": [{"id": o[0], "total": o[1], "status": o[2]} for o in orders]
    }

Edge Functions Tutorial (15 Minutes)

Example 1: CDC Trigger for Audit Logging

from heliosdb import heliosdb_function, execute
import json
from datetime import datetime

@heliosdb_function
def audit_user_changes(event: dict):
    """Log all user table changes for compliance (SOX, HIPAA, GDPR)"""

    execute("""
        INSERT INTO audit_log
        (table_name, operation, record_id, old_data, new_data, changed_by, timestamp)
        VALUES (?, ?, ?, ?, ?, ?, ?)
    """, [
        event['table'],
        event['operation'],
        event.get('new_row', event.get('old_row', {})).get('id'),
        json.dumps(event.get('old_row', {})),
        json.dumps(event.get('new_row', {})),
        event.get('user_id', 'system'),
        datetime.now().isoformat()
    ])

Register CDC trigger:

heliosdb-sdk-python build audit_logger.py
heliosdb-cli wasm deploy audit_logger.wasm

heliosdb-cli edge register-cdc \
  --table users \
  --operations INSERT,UPDATE,DELETE \
  --function audit_user_changes

Test:

heliosdb-cli query "INSERT INTO users (name, email) VALUES ('Bob', 'bob@example.com')"
heliosdb-cli query "SELECT * FROM audit_log ORDER BY timestamp DESC LIMIT 1"

Example 2: HTTP Webhook for GitHub Events

from heliosdb import heliosdb_function, execute

@heliosdb_function
def handle_github_push(payload: dict):
    """Auto-deploy on push to main branch"""

    if payload['ref'] == 'refs/heads/main':
        repo = payload['repository']['name']
        commit = payload['head_commit']['id']
        author = payload['pusher']['name']

        # Log deployment
        execute("""
            INSERT INTO deployments (repository, commit_sha, author, status, created_at)
            VALUES (?, ?, ?, 'pending', NOW())
        """, [repo, commit, author])

        # Trigger CI/CD pipeline (example)
        # trigger_ci_pipeline(repo, commit)

Register webhook:

heliosdb-cli webhook create \
  --endpoint /github/push \
  --provider github \
  --secret "your-webhook-secret" \
  --function handle_github_push

GitHub webhook URL: https://your-server.com:8080/github/push

Example 3: Cron Job for Cleanup

from heliosdb import heliosdb_function, execute, emit_event

@heliosdb_function
def daily_cleanup():
    """Delete old records at 2 AM every day"""

    # Delete old logs (>90 days)
    result1 = execute("DELETE FROM logs WHERE created_at < NOW() - INTERVAL '90 days'")

    # Delete expired sessions (>7 days)
    result2 = execute("DELETE FROM sessions WHERE last_activity < NOW() - INTERVAL '7 days'")

    # Emit event
    emit_event("cleanup_completed", {
        "deleted_logs": result1.rows_affected(),
        "deleted_sessions": result2.rows_affected()
    })

Schedule cron job:

heliosdb-cli scheduler create \
  --name daily_cleanup \
  --cron "0 2 * * *" \
  --timezone "America/New_York" \
  --function daily_cleanup

Production Deployment (30 Minutes)

Step 1: Docker Compose Setup

version: '3.8'

services:
  heliosdb:
    image: heliosdb/heliosdb:v6.0.0
    ports:
      - "5432:5432"
      - "8080:8080"
      - "9090:9090"
    volumes:
      - ./data:/var/lib/heliosdb/data
      - ./config.toml:/etc/heliosdb/config.toml
    environment:
      - HELIOSDB_CONFIG=/etc/heliosdb/config.toml

  prometheus:
    image: prom/prometheus:latest
    ports:
      - "9091:9090"
    volumes:
      - ./prometheus.yml:/etc/prometheus/prometheus.yml
    command:
      - '--config.file=/etc/prometheus/prometheus.yml'

  grafana:
    image: grafana/grafana:latest
    ports:
      - "3000:3000"
    environment:
      - GF_SECURITY_ADMIN_PASSWORD=admin

Step 2: Configure Monitoring

scrape_configs:
  - job_name: 'heliosdb'
    static_configs:
      - targets: ['heliosdb:9090']
    scrape_interval: 15s

Step 3: Start Stack

docker-compose up -d

Step 4: Access Services

HeliosDB: postgresql://localhost:5432
Webhook Server: http://localhost:8080
Prometheus: http://localhost:9091
Grafana: http://localhost:3000 (admin/admin)

Next Steps

You’ve completed the getting started guide!

What’s Next:

Read the API Reference for complete SDK documentation
Explore 91 production examples for real-world use cases
Set up monitoring dashboards
Join the community forum for support

Happy coding!