HeliosDB v6.0 API Reference

HeliosDB v6.0 API Reference

Complete API documentation for all HeliosDB v6.0 SDKs and interfaces.

---

Python SDK API

Module: heliosdb

Decorators

@heliosdb_function

Marks a function for export as a WASM stored procedure.

Signature:

def heliosdb_function(func: Callable) -> Callable

Example:

from heliosdb import heliosdb_function

@heliosdb_function
def add(a: int, b: int) -> int:
    return a + b

@transaction

Wraps function in automatic transaction with rollback on exception.

Signature:

def transaction(func: Callable) -> Callable

Example:

from heliosdb import transaction, execute

@transaction
def transfer(from_id: int, to_id: int, amount: float):
    execute("UPDATE accounts SET balance = balance - ? WHERE id = ?", [amount, from_id])
    execute("UPDATE accounts SET balance = balance + ? WHERE id = ?", [amount, to_id])

Functions

query(sql: str, params: list = None) -> Result

Execute SELECT query and return result set.

Parameters:

• sql (str): SQL query string
• params (list, optional): Query parameters

Returns: Result object

Example:

from heliosdb import query

result = query("SELECT * FROM users WHERE id = ?", [42])
row = result.fetchone()
print(row[0], row[1])  # id, name

execute(sql: str, params: list = None) -> ExecuteResult

Execute INSERT/UPDATE/DELETE and return affected rows.

Parameters:

• sql (str): SQL statement
• params (list, optional): Statement parameters

Returns: ExecuteResult object

Example:

from heliosdb import execute

result = execute("INSERT INTO users (name, email) VALUES (?, ?)", ["Alice", "alice@example.com"])
print(result.rows_affected())  # 1
print(result.last_insert_id())  # 123

emit_event(event_type: str, payload: dict)

Trigger edge function event.

Parameters:

• event_type (str): Event type identifier
• payload (dict): Event data

Example:

from heliosdb import emit_event

emit_event("user_created", {"user_id": 123, "email": "alice@example.com"})

Context Managers

transaction()

Manual transaction control.

Example:

from heliosdb import transaction, execute

with transaction():
    execute("INSERT INTO orders (user_id, total) VALUES (?, ?)", [1, 99.99])
    execute("INSERT INTO order_items (order_id, product_id) VALUES (?, ?)", [1, 42])
    # Auto-commit on exit, rollback on exception

Classes

Result

Query result set.

Methods:

• fetchone() -> tuple | None: Fetch next row
• fetchall() -> list[tuple]: Fetch all rows
• fetchmany(size: int) -> list[tuple]: Fetch N rows
• fetchone_async() -> tuple | None: Async fetch (for async functions)
• fetchall_async() -> list[tuple]: Async fetch all

Example:

result = query("SELECT id, name FROM users")

# Iterate
for row in result:
    print(row[0], row[1])

# Fetch all
rows = result.fetchall()

ExecuteResult

Execution result for DML operations.

Methods:

• rows_affected() -> int: Number of affected rows
• last_insert_id() -> int: Last inserted ID (for INSERT)

---

JavaScript SDK API

Module: heliosdb

Functions

heliosdbFunction(func: Function) -> Function

Export function as WASM stored procedure.

Example:

import { heliosdbFunction, query } from 'heliosdb';

export const getUser = heliosdbFunction(async (userId) => {
  const result = await query('SELECT * FROM users WHERE id = ?', [userId]);
  return result.fetchOne();
});

query(sql: string, params?: any[]) -> Promise<Result>

Execute SELECT query.

Example:

import { query } from 'heliosdb';

const result = await query('SELECT * FROM users WHERE email = ?', ['alice@example.com']);
const rows = await result.fetchAll();
console.log(rows);

execute(sql: string, params?: any[]) -> Promise<ExecuteResult>

Execute INSERT/UPDATE/DELETE.

Example:

import { execute } from 'heliosdb';

const result = await execute(
  'INSERT INTO users (name, email) VALUES (?, ?)',
  ['Bob', 'bob@example.com']
);
console.log(result.rowsAffected(), result.lastInsertId());

transaction(callback: Function) -> Promise<any>

Execute within transaction.

Example:

import { transaction, execute } from 'heliosdb';

await transaction(async () => {
  await execute('INSERT INTO orders (user_id) VALUES (?)', [1]);
  await execute('UPDATE inventory SET quantity = quantity - 1 WHERE product_id = ?', [42]);
});

emitEvent(eventType: string, payload: object) -> void

Trigger edge function event.

Example:

import { emitEvent } from 'heliosdb';

emitEvent('order_placed', { orderId: 123, userId: 1 });

Classes

Result

Query result set.

Methods:

• fetchOne() -> Promise<any[] | null>
• fetchAll() -> Promise<any[][]>
• fetchMany(size: number) -> Promise<any[][]>

ExecuteResult

Execution result.

Methods:

• rowsAffected() -> number
• lastInsertId() -> number

---

Go SDK API

Package: github.com/heliosdb/wasm-sdk-go/heliosdb

Functions

Query(sql string, params ...interface{}) (*Result, error)

Execute SELECT query.

Example:

import "github.com/heliosdb/wasm-sdk-go/heliosdb"

result, err := heliosdb.Query("SELECT id, name FROM users WHERE id = ?", 42)
if err != nil {
    return heliosdb.Error(err)
}
rows := result.Rows()

Execute(sql string, params ...interface{}) (*ExecuteResult, error)

Execute INSERT/UPDATE/DELETE.

Example:

result, err := heliosdb.Execute(
    "INSERT INTO users (name, email) VALUES (?, ?)",
    "Alice", "alice@example.com",
)
if err != nil {
    return heliosdb.Error(err)
}
fmt.Println(result.RowsAffected(), result.LastInsertID())

Transaction(fn func() error) error

Execute within transaction.

Example:

err := heliosdb.Transaction(func() error {
    _, err := heliosdb.Execute("INSERT INTO orders (user_id) VALUES (?)", 1)
    if err != nil {
        return err
    }
    _, err = heliosdb.Execute("UPDATE inventory SET qty = qty - 1 WHERE id = ?", 42)
    return err
})

EmitEvent(eventType string, payload interface{}) error

Trigger edge function event.

Example:

heliosdb.EmitEvent("user_created", map[string]interface{}{
    "user_id": 123,
    "email": "alice@example.com",
})

Helper Functions

JSON(v interface{}) []byte

Serialize value to JSON for return.

Example:

//export get_user
func GetUser(userId int32) []byte {
    result, _ := heliosdb.Query("SELECT id, name, email FROM users WHERE id = ?", userId)
    rows := result.Rows()
    return heliosdb.JSON(rows[0])
}

Error(err error) []byte

Return error as JSON.

Example:

if err != nil {
    return heliosdb.Error(err)
}

Types

Result

Query result.

Fields:

• Rows() [][]interface{}

ExecuteResult

Execution result.

Methods:

• RowsAffected() int64
• LastInsertID() int64

---

Rust SDK API

Crate: heliosdb-wasm-sdk

Macros

#[heliosdb_function]

Export function as WASM stored procedure.

Example:

use heliosdb_wasm_sdk::{heliosdb_function, query, Value};

#[heliosdb_function]
fn get_user(user_id: i64) -> Result<Vec<Value>, String> {
    let rows = query("SELECT id, name, email FROM users WHERE id = ?", &[Value::from(user_id)])?;
    Ok(rows)
}

query!(sql, params...)

Type-safe query macro.

Example:

use heliosdb_wasm_sdk::query;

#[heliosdb_function]
fn get_users() -> Result<Vec<User>, String> {
    let rows = query!("SELECT id, name, email FROM users")?;
    Ok(rows.into_iter().map(|r| User::from(r)).collect())
}

Functions

query(sql: &str, params: &[Value]) -> Result<Vec<Value>, String>

Execute SELECT query.

Example:

use heliosdb_wasm_sdk::{query, Value};

let rows = query("SELECT * FROM users WHERE id = ?", &[Value::from(42)])?;

execute(sql: &str, params: &[Value]) -> Result<ExecuteResult, String>

Execute INSERT/UPDATE/DELETE.

Example:

use heliosdb_wasm_sdk::{execute, Value};

let result = execute(
    "INSERT INTO users (name, email) VALUES (?, ?)",
    &[Value::from("Alice"), Value::from("alice@example.com")]
)?;
println!("Rows affected: {}", result.rows_affected);

transaction<F>(f: F) -> Result<(), String> where F: FnOnce() -> Result<(), String>

Execute within transaction.

Example:

use heliosdb_wasm_sdk::transaction;

transaction(|| {
    execute("INSERT INTO orders (user_id) VALUES (?)", &[Value::from(1)])?;
    execute("UPDATE inventory SET qty = qty - 1", &[])?;
    Ok(())
})?;

emit_event(event_type: &str, payload: Value) -> Result<(), String>

Trigger edge function event.

Example:

use heliosdb_wasm_sdk::emit_event;

emit_event("user_created", Value::Object(HashMap::from([
    ("user_id".to_string(), Value::from(123)),
])))?;

Types

Value

SQL value enum.

Variants:

• Value::Null
• Value::Bool(bool)
• Value::Int(i64)
• Value::Float(f64)
• Value::String(String)
• Value::Bytes(Vec<u8>)
• Value::Array(Vec<Value>)
• Value::Object(HashMap<String, Value>)

ExecuteResult

Execution result.

Fields:

• rows_affected: usize
• last_insert_id: Option<i64>

---

HTTP API

Webhook Management

POST /api/webhooks

Register new webhook.

Request:

{
  "endpoint": "/github/push",
  "provider": "github",
  "secret": "webhook-secret",
  "function": "handle_github_push",
  "ip_whitelist": ["192.30.252.0/22"]
}

Response:

{
  "id": "wh_123abc",
  "endpoint": "/github/push",
  "created_at": "2025-10-30T12:00:00Z"
}

GET /api/webhooks

List all webhooks.

Response:

{
  "webhooks": [
    {
      "id": "wh_123abc",
      "endpoint": "/github/push",
      "provider": "github",
      "enabled": true
    }
  ]
}

DELETE /api/webhooks/:id

Delete webhook.

Response: 204 No Content

Scheduler API

POST /api/jobs

Create cron job.

Request:

{
  "name": "daily_cleanup",
  "cron": "0 2 * * *",
  "timezone": "America/New_York",
  "function": "daily_cleanup",
  "enabled": true
}

Response:

{
  "id": "job_456def",
  "name": "daily_cleanup",
  "next_run": "2025-10-31T02:00:00-04:00"
}

GET /api/jobs

List all jobs.

Response:

{
  "jobs": [
    {
      "id": "job_456def",
      "name": "daily_cleanup",
      "cron": "0 2 * * *",
      "enabled": true,
      "last_run": "2025-10-30T02:00:00-04:00",
      "next_run": "2025-10-31T02:00:00-04:00"
    }
  ]
}

---

Prometheus Metrics

WASM Metrics

heliosdb_wasm_invocations_total{module, function, status}
heliosdb_wasm_execution_duration_seconds{module, function}
heliosdb_wasm_cache_hits_total{tier}
heliosdb_wasm_pool_utilization{module}
heliosdb_wasm_memory_bytes{module}

Edge Function Metrics

heliosdb_edge_events_total{source, status}
heliosdb_cdc_events_total{table, operation}
heliosdb_webhook_requests_total{provider, status}
heliosdb_cron_executions_total{job, status}

Database Metrics

heliosdb_queries_total{status}
heliosdb_query_duration_seconds
heliosdb_connections_active
heliosdb_transactions_total{status}

---

Configuration Reference

Complete Config Schema

[server]
host = "0.0.0.0"
port = 5432
max_connections = 100

[wasm.cache]
aot_enabled = true
aot_cache_dir = "/var/lib/heliosdb/wasm_cache"
aot_max_size_gb = 5
aot_max_age_days = 7

[wasm.pool]
instance_pool_min_per_module = 5
instance_pool_max_per_module = 20
instance_pool_idle_timeout_secs = 300

[wasm.execution]
default_timeout_ms = 5000
default_memory_limit_mb = 16
enable_fuel_metering = true

[edge_functions]
enabled = true
cdc_enabled = true
webhook_server_enabled = true
scheduler_enabled = true

[monitoring]
prometheus_enabled = true
prometheus_port = 9090
opentelemetry_enabled = true

---

For complete examples, see /examples/ directory.