Getting Started with HeliosDB Full

Container images: HeliosDB Full images are not published on Docker Hub or any other public registry. Images and Helm charts are provided through private registry access during onboarding: contact sales@heliosdb.com. The examples on this page use heliosdb-full:<tag>, an image built locally from the licensed source distribution (docker build -t heliosdb-full:<tag> .); replace it with the image reference you receive if you use the private registry.

This guide gets a HeliosDB Full server running and connects an application to it in a few minutes.

---

Quick Start (5 Minutes)

Step 1: Install HeliosDB

Option A: Docker (Easiest)

docker build -t heliosdb-full:<tag> .   # from the licensed source distribution
docker run -d --name heliosdb -p 5432:5432 \
  -e HELIOSDB_ALLOW_EXTERNAL=1 \
  -e HELIOSDB_SUPERUSER_PASSWORD='choose-a-strong-password' \
  heliosdb-full:<tag>

The built-in superuser is postgres. If you do not set HELIOSDB_SUPERUSER_PASSWORD, the server generates a random password and prints it once in the log (docker logs heliosdb).

Option B: Binary

HeliosDB Full is distributed to licensed customers. Native binaries, container images and source access are provided during onboarding — contact sales@heliosdb.com for access.

The server binary is heliosdb-full; run heliosdb-full --help for its options and heliosdb-full --show-features to list what the build provides.

Step 2: Verify Installation

HeliosDB Full speaks the PostgreSQL wire protocol, so use psql (or any PostgreSQL client):

export PGPASSWORD='choose-a-strong-password'
psql -h localhost -p 5432 -U postgres -c "SELECT version()"
# Output: PostgreSQL 17.0 (HeliosDB x.y.z) on x86_64-linux, 64-bit

Step 3: Create Your First Database

psql -h localhost -p 5432 -U postgres -c "CREATE DATABASE my_app"
psql -h localhost -p 5432 -U postgres -d my_app \
  -c "CREATE TABLE users (id SERIAL PRIMARY KEY, name TEXT, email TEXT)"

Step 4: Connect from your application

HeliosDB Full speaks the PostgreSQL wire protocol on port 5432, so any PostgreSQL driver works. For example, with Python and psycopg:

pip install "psycopg[binary]"

import psycopg

with psycopg.connect("host=localhost port=5432 dbname=my_app user=postgres password=choose-a-strong-password") as conn:
    conn.execute("INSERT INTO users (name, email) VALUES (%s, %s)", ("Ada", "ada@example.com"))
    print(conn.execute("SELECT count(*) FROM users").fetchone())

See Connecting for other languages.

---

WASM procedures and edge functions

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. Serverless edge functions for HeliosDB Full are on the roadmap and are not available in the current release. The Python tooling that earlier versions of this guide described (pip install heliosdb-sdk-python and a heliosdb-sdk-python build command) was never published.

You can already write and unit-test procedures in Go with the published Go WASM SDK. It builds modules for the WASM host in the HeliosDB Full source. See the WASM Procedures Quick Start.

---

Production Deployment (30 Minutes)

Step 1: Docker Compose Setup

docker-compose.yml

version: '3.8'

services:
  heliosdb:
    image: heliosdb-full:latest  # pin a release tag in production
    ports:
      - "5432:5432"
      - "8443:8443"   # HTTP gateway
      - "9090:9090"
    volumes:
      - ./data:/var/lib/heliosdb/data
      - ./config.toml:/etc/heliosdb/config.toml
    environment:
      - HELIOSDB_CONFIG=/etc/heliosdb/config.toml
      - HELIOSDB_ALLOW_EXTERNAL=1   # required to bind all interfaces in the container

  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

prometheus.yml

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
• HTTP gateway: http://localhost:8443
• Prometheus: http://localhost:9091
• Grafana: http://localhost:3000 (admin/admin)

---

Next Steps

What’s Next:

1. Read the API Reference for complete SDK documentation
2. Set up monitoring dashboards
3. Community: Discord