--- title: "Get Started with HeliosDB in 5 Minutes" --- # 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](mailto:sales@heliosdb.com). In > the examples on this page, replace `` 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) ```bash 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 \ \ --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: ```bash heliosdb-full --data-dir ./heliosdb-data --enable-mysql --enable-oracle ``` It binds `127.0.0.1` by default; see [Remote access](#remote-access-and-tls) below. **Verify it's running:** ```bash 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 ```bash 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 ```bash mysql -h 127.0.0.1 -P 3306 -u postgres -p postgres ``` ```python 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: ```sql CREATE ROLE app LOGIN PASSWORD 'app-password'; ``` :::caution[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`. ```python 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](/docs/full/guides/user/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: ```bash 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](/docs/full/reference/api/http_rest_api/). ### Option E: Python (PostgreSQL driver) ```bash 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 ```sql CREATE TABLE users ( id SERIAL PRIMARY KEY, name TEXT NOT NULL, email TEXT UNIQUE, created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP ); ``` ### Insert Data ```sql INSERT INTO users (name, email) VALUES ('Alice Anderson', 'alice@example.com'), ('Bob Builder', 'bob@example.com'), ('Carol Chen', 'carol@example.com'); ``` ### Query Data ```sql 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 ```sql 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: ```bash # 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 ```sql SHOW SERVER STATUS; -- version, uptime, protocols, table count SHOW PROTOCOLS; -- listeners and ports SHOW CONNECTIONS; -- who is connected ``` ```bash 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](/docs/full/reference/configuration/). --- ## 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? ```bash docker run -d --name heliosdb -p 127.0.0.1:15432:5432 ... 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: ```bash docker rm -f heliosdb export HELIOSDB_SUPERUSER_PASSWORD='new-strong-password' docker run -d --name heliosdb -e HELIOSDB_SUPERUSER_PASSWORD ... --enable-mysql --enable-oracle ``` --- ## Stop HeliosDB ```bash 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](/docs/full/guides/user/connecting/)** — every listener, its credentials and client examples - **[Server Configuration Reference](/docs/full/reference/configuration/)** — flags, environment variables, config file - **[HTTP REST API](/docs/full/reference/api/http_rest_api/)** — SQL over HTTP - **[Production Deployment Guide](/docs/full/deployment/production_deployment_guide/)** — backups, security, troubleshooting ## Quick Reference ```bash # 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 # Connect psql "host=127.0.0.1 user=postgres" # Logs docker logs -f heliosdb # Stop docker stop heliosdb ``` ### Essential SQL ```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; ```