Get Started with HeliosDB in 5 Minutes

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. In the examples on this page, replace <heliosdb-full-image> with the image reference you receive.

HeliosDB Full is one server that your existing database clients connect to. PostgreSQL, MySQL and Oracle clients read and write the same tables. MongoDB, Cassandra and SQL Server clients can connect and authenticate, and reading and writing HeliosDB tables through them is planned. The Redis listener keeps an in-memory keyspace that is not persisted. This guide starts the server with the PostgreSQL, MySQL and Oracle listeners and connects with each.

---

Prerequisites

• Docker, and the HeliosDB Full image from onboarding (or the heliosdb-full binary on a Linux host)
• A client for the protocol you want to try: psql, the mysql client, or python-oracledb (pip install oracledb)

---

Step 1: Start HeliosDB (30 seconds)

export HELIOSDB_SUPERUSER_PASSWORD='choose-a-strong-password'
export HELIOSDB_ORACLE_NATIVE_PASSWORD='choose-another-password'

docker run -d --name heliosdb \
  -e HELIOSDB_SUPERUSER_PASSWORD \
  -e HELIOSDB_ORACLE_NATIVE_PASSWORD \
  -p 127.0.0.1:5432:5432 \
  -p 127.0.0.1:3306:3306 \
  -p 127.0.0.1:1521:1521 \
  -p 127.0.0.1:8443:8443 \
  -v heliosdb-data:/var/lib/heliosdb/data \
  <heliosdb-full-image> \
  --enable-mysql --enable-oracle

-e NAME without a value passes the variable from your shell, so the passwords do not appear in the command line.

What just happened?

Port	Listener	State
5432	PostgreSQL	on by default
8443	HTTP gateway (plain HTTP)	on by default
3306	MySQL	enabled by --enable-mysql
1521	Oracle TNS	enabled by --enable-oracle

Arguments after the image name are passed to the heliosdb-full server. The other listeners stay off until you add --enable-mongodb, --enable-cassandra, --enable-sqlserver or --enable-redis.

Without a container, run the binary directly:

heliosdb-full --data-dir ./heliosdb-data --enable-mysql --enable-oracle

It binds 127.0.0.1 by default; see Remote access below.

Verify it’s running:

docker logs heliosdb 2>&1 | grep -E "listening|Server ready"
# PostgreSQL protocol listening on 0.0.0.0:5432
# MySQL protocol listening on 0.0.0.0:3306
# HTTP Gateway listening on 0.0.0.0:8443
# Oracle (TNS) protocol listening on 0.0.0.0:1521
# Server ready - accepting connections

curl -s http://127.0.0.1:8443/health
# {"status":"healthy","version":"..."}

---

Step 2: Connect Your Way (Pick One)

Credentials at a glance

Listener	User	Password
PostgreSQL	postgres (built-in superuser), or a role you create	HELIOSDB_SUPERUSER_PASSWORD, or the role’s password
MySQL	a role from the role catalog, for example postgres or app	any non-empty password today (not verified yet, see Option B)
Oracle	any user name, for example app	HELIOSDB_ORACLE_NATIVE_PASSWORD (if unset: the user name, so set it)
HTTP	—	API key in HELIOSDB_API_KEY (see Option D)

If you start the server without HELIOSDB_SUPERUSER_PASSWORD, it generates a password and prints it once in the log (docker logs heliosdb).

Option A: PostgreSQL client

psql "host=127.0.0.1 port=5432 user=postgres dbname=postgres"
# Password: the value of HELIOSDB_SUPERUSER_PASSWORD

Any PostgreSQL driver, ORM or tool (JDBC, psycopg, node-postgres, pgAdmin, DBeaver) connects the same way.

Option B: MySQL client

mysql -h 127.0.0.1 -P 3306 -u postgres -p postgres

import os, pymysql

conn = pymysql.connect(host="127.0.0.1", port=3306, user="postgres",
                       password=os.environ["HELIOSDB_SUPERUSER_PASSWORD"], database="postgres")
with conn.cursor() as cur:
    cur.execute("SELECT version()")
    print(cur.fetchone())

The MySQL listener accepts the roles of the server’s role catalog. Create an application role once over PostgreSQL and use it from MySQL clients:

CREATE ROLE app LOGIN PASSWORD 'app-password';

MySQL passwords are not verified yet

The MySQL listener currently checks that the role exists and that a non-empty password was sent, but not the password itself. Keep --enable-mysql on loopback (the default bind) or a trusted private network, and use the PostgreSQL listener where authentication matters. The MySQL listener has no TLS.

Option C: Oracle client

The Oracle listener serves thin-mode clients (it has been tested with python-oracledb in thin mode). The service name is not checked; use heliosdb.

import os, oracledb

conn = oracledb.connect(user="app",
                        password=os.environ["HELIOSDB_ORACLE_NATIVE_PASSWORD"],
                        dsn="127.0.0.1:1521/heliosdb")
conn.autocommit = True
cur = conn.cursor()
cur.execute("SELECT COUNT(*) FROM users")
print(cur.fetchone())

JDBC thin URL: jdbc:oracle:thin:@//127.0.0.1:1521/heliosdb.

On the Oracle listener each statement commits as it runs, and the driver’s commit()/rollback() calls are not supported yet, so enable autocommit as above. Open a new cursor for each statement. See Connecting for the details of each listener.

Option D: HTTP REST API

Set an API key when you start the container (-e HELIOSDB_API_KEY), then:

curl -s -X POST http://127.0.0.1:8443/api/v1/query \
  -H "Authorization: Bearer $HELIOSDB_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"query": "SELECT version()"}'

See the HTTP REST API reference.

Option E: Python (PostgreSQL driver)

pip install "psycopg[binary]"
python3 - <<'EOF'
import os, psycopg
with psycopg.connect(host="127.0.0.1", port=5432, user="postgres",
                     password=os.environ["HELIOSDB_SUPERUSER_PASSWORD"], dbname="postgres") as conn:
    print(conn.execute("SELECT version()").fetchone()[0])
EOF

---

Step 3: Run Your First Queries (2 minutes)

Run these from psql (or any client above):

Create a Table

CREATE TABLE users (
    id SERIAL PRIMARY KEY,
    name TEXT NOT NULL,
    email TEXT UNIQUE,
    created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP
);

Insert Data

INSERT INTO users (name, email) VALUES
    ('Alice Anderson', 'alice@example.com'),
    ('Bob Builder', 'bob@example.com'),
    ('Carol Chen', 'carol@example.com');

Query Data

SELECT id, name, email FROM users ORDER BY id;

 id |      name      |       email
----+----------------+-------------------
  1 | Alice Anderson | alice@example.com
  2 | Bob Builder    | bob@example.com
  3 | Carol Chen     | carol@example.com

Constraints Are Enforced

INSERT INTO users (name, email) VALUES ('Dup', 'alice@example.com');
-- ERROR:  duplicate key value violates unique constraint "users_email_key"

---

Step 4: One Database, Several Protocols

The table you created over PostgreSQL is visible to the other listeners:

# MySQL
mysql -h 127.0.0.1 -P 3306 -u postgres -p postgres -e "SELECT name, email FROM users WHERE id = 1"

# Oracle (python-oracledb)
python3 -c "
import os, oracledb
c = oracledb.connect(user='app', password=os.environ['HELIOSDB_ORACLE_NATIVE_PASSWORD'], dsn='127.0.0.1:1521/heliosdb')
cur = c.cursor(); cur.execute('SELECT name FROM users WHERE id = :id', id=2); print(cur.fetchall())"

---

Step 5: Check the Server

SHOW SERVER STATUS;   -- version, uptime, protocols, table count
SHOW PROTOCOLS;       -- listeners and ports
SHOW CONNECTIONS;     -- who is connected

curl -s http://127.0.0.1:8443/ready     # {"ready":true}
docker exec heliosdb heliosdb-full --show-features

---

Remote Access and TLS

The container publishes the ports on 127.0.0.1 above. To reach the server from other hosts:

• Container: publish on a private address (-p 10.0.0.12:5432:5432) and firewall it.
• Binary: --bind-addr 10.0.0.12 --allow-external (the server refuses non-loopback addresses without --allow-external).
• TLS on PostgreSQL: HeliosDB Full listeners do not terminate TLS; put a TLS-terminating proxy in front. Native PostgreSQL TLS is planned for the next release: mount a certificate and start with --tls-cert /tls/server.crt --tls-key /tls/server.key --tls-require; clients use sslmode=require or verify-full.
• MySQL, Oracle and HTTP are plaintext: keep them on a private network or behind a TLS proxy.

All flags are in the Server Configuration Reference.

---

Troubleshooting

Can’t connect?

1. docker logs heliosdb shows one listening on line per listener. MySQL and Oracle need --enable-mysql / --enable-oracle after the image name.
2. Check the published ports: docker port heliosdb.
3. Wrong password: the PostgreSQL listener uses the superuser password or a role’s password; the Oracle listener uses HELIOSDB_ORACLE_NATIVE_PASSWORD. The MySQL listener refuses unknown role names and empty passwords.

Port already in use?

docker run -d --name heliosdb -p 127.0.0.1:15432:5432 ... <heliosdb-full-image>
psql "host=127.0.0.1 port=15432 user=postgres"

Forgot the password?

Recreate the container with a new HELIOSDB_SUPERUSER_PASSWORD; the data in the heliosdb-data volume is kept:

docker rm -f heliosdb
export HELIOSDB_SUPERUSER_PASSWORD='new-strong-password'
docker run -d --name heliosdb -e HELIOSDB_SUPERUSER_PASSWORD ... <heliosdb-full-image> --enable-mysql --enable-oracle

---

Stop HeliosDB

docker stop heliosdb          # flushes storage and stops
docker rm heliosdb            # remove the container (the volume keeps the data)
docker volume rm heliosdb-data   # delete the data as well

---

What’s Next?

• Connecting — every listener, its credentials and client examples
• Server Configuration Reference — flags, environment variables, config file
• HTTP REST API — SQL over HTTP
• Production Deployment Guide — backups, security, troubleshooting

Quick Reference

# Start (PostgreSQL + HTTP; add --enable-mysql / --enable-oracle as needed)
docker run -d --name heliosdb -e HELIOSDB_SUPERUSER_PASSWORD -p 127.0.0.1:5432:5432 \
  -v heliosdb-data:/var/lib/heliosdb/data <heliosdb-full-image>

# Connect
psql "host=127.0.0.1 user=postgres"

# Logs
docker logs -f heliosdb

# Stop
docker stop heliosdb

Essential SQL

CREATE TABLE t (id SERIAL PRIMARY KEY, name TEXT);
INSERT INTO t (name) VALUES ('a'), ('b');
SELECT * FROM t;
CREATE ROLE app LOGIN PASSWORD '...';
SHOW SERVER STATUS;
EXPLAIN SELECT * FROM t WHERE id = 1;