---
title: "Getting Started with HeliosDB Full"
---

# 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](mailto: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)
```bash
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](mailto: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):

```bash
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
```bash
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](https://www.psycopg.org/):

```bash
pip install "psycopg[binary]"
```

```python
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](https://www.heliosdb.com/docs/full/guides/user/connecting/) for other languages.

---

## WASM procedures and edge functions

:::caution[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](https://github.com/HeliosDatabase/HeliosDB-SDKs/tree/main/sdks/go/wasm).
It builds modules for the WASM host in the HeliosDB Full source. See the
[WASM Procedures Quick Start](https://www.heliosdb.com/docs/full/guides/features/wasm_procedures_quick_start/).

---

## Production Deployment (30 Minutes)

### Step 1: Docker Compose Setup

```yaml
# 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

```yaml
# prometheus.yml
scrape_configs:
  - job_name: 'heliosdb'
    static_configs:
      - targets: ['heliosdb:9090']
    scrape_interval: 15s
```

### Step 3: Start Stack

```bash
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](https://www.heliosdb.com/docs/full/reference/api_reference/) for complete SDK documentation
3. Set up monitoring dashboards
4. Community: [Discord](https://discord.gg/yTykuUrFXc)