HeliosDB Full API Reference

Reference for the WASM procedure SDK, the planned webhook and scheduler HTTP API, Prometheus metric names and the server configuration schema of HeliosDB Full.

---

WASM procedure SDKs

WASM procedures are not yet available in the server

The current heliosdb-full server does not run WASM procedures. SQL that would create or call one fails with SQLSTATE 0A000. The Go SDK below builds modules for the WASM host in the HeliosDB Full source, so they will load once the server enables that host.

Language	Published SDK
Go (TinyGo)	github.com/HeliosDatabase/HeliosDB-SDKs/sdks/go/wasm (below)
Python, JavaScript, Rust	None. The heliosdb Python module, the heliosdb JavaScript module and the heliosdb-wasm-sdk crate described in earlier versions of this page are not published.

For application access to HeliosDB Full from these languages, use a PostgreSQL driver: see SDKs.

Go SDK API

Package: github.com/HeliosDatabase/HeliosDB-SDKs/sdks/go/wasm/heliosdb

Install with go get github.com/HeliosDatabase/HeliosDB-SDKs/sdks/go/wasm@latest and build procedures with tinygo build -target=wasm-unknown -gc=conservative -opt=z -no-debug -o procedure.wasm .. Procedures are exported with //export and take and return WASM scalars. The module imports only the host’s env functions (no WASI). Source and examples: sdks/go/wasm.

SQL

Function	Description
Exec(sql string) (int64, error)	Run a statement and return the rows affected (heliosdb_execute)
Quote(s), QuoteIdent(s), Int64(v)	Build SQL literals (the ABI has no bind parameters)

Procedures cannot read query results. The host functions that return rows write them to a host-chosen address in the module’s memory, so the SDK does not expose them (see Host Functions).

Example:

import "github.com/HeliosDatabase/HeliosDB-SDKs/sdks/go/wasm/heliosdb"

//export deactivate_user
func deactivateUser(id int64) int32 {
    if _, err := heliosdb.Exec("UPDATE users SET active = false WHERE id = " + heliosdb.Int64(id)); err != nil {
        heliosdb.LogError(err.Error())
        return -1
    }
    return 0
}

Transactions

Function	Description
Begin() (Tx, error)	Start a transaction
Tx.Commit() error, Tx.Rollback() error	Finish it
WithTx(fn func(Tx) error) error	Commit on success, roll back on error

Key-value store and logging

Function	Description
StorageWrite(key string, value []byte) error	Write to the host key-value store
Log(level, msg), LogTrace … LogError	Write to the server log

Failed host calls return *heliosdb.HostError with the host’s return code.

Testing

github.com/HeliosDatabase/HeliosDB-SDKs/sdks/go/wasm/heliosdbtest provides an in-memory host: fake := heliosdbtest.Install(t) records SQL, transactions, logs and key-value writes so procedures can be tested with go test.

---

HTTP API

Planned

Webhooks, the cron scheduler and edge functions for HeliosDB Full are planned and are not in the current release. The /api/webhooks and /api/jobs routes below describe the planned API; the HTTP gateway (port 8443) does not serve them yet. What the server answers over HTTP today is /health, /ready, /status, POST /api/v1/query and the AI routes: see the HTTP REST API reference.

Webhook Management (planned)

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 (planned)

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

Planned

Serverless edge functions for HeliosDB Full are on the roadmap and are not available in the current release; the edge, webhook and cron metrics below arrive with them.

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

# Planned: [edge_functions] is not read by the current release
[edge_functions]
enabled = true
cdc_enabled = true
webhook_server_enabled = true
scheduler_enabled = true

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

The [edge_functions] section (edge functions, CDC triggers, the webhook server and the scheduler) is planned together with those features.