---
title: "HeliosDB Protocol Documentation Hub"
---

# HeliosDB Protocol Documentation Hub

This section is the reference for the wire protocols and HTTP interfaces of HeliosDB
Full. HeliosDB Full opens listeners for PostgreSQL, MySQL, Oracle, MongoDB,
Cassandra, Redis and SQL Server plus an HTTP gateway, all inside the one
`heliosdb-full` server process. The PostgreSQL, MySQL and Oracle listeners and the
HTTP gateway read and write the shared tables. The Redis listener keeps data in
memory. MongoDB, Cassandra and SQL Server clients can connect and authenticate, and
reading and writing HeliosDB tables through them is planned.

## Listeners served by `heliosdb-full`

| Protocol | Default port | Enable | Log on with | Compatibility |
|----------|--------------|--------|-------------|---------------|
| **PostgreSQL** | 5432 | on (`--no-postgres` turns it off) | `postgres` or a role (SCRAM-SHA-256); TLS planned for the next release | Primary interface; PostgreSQL drivers, ORMs and tools |
| **HTTP gateway** | 8443 (plain HTTP) | on (`--no-http` turns it off) | `HELIOSDB_API_KEY` | `POST /api/v1/query`, see [HTTP/REST API](/docs/full/reference/api/http_rest_api/) |
| **MySQL** | 3306 | `--enable-mysql` | a role name from the role catalog (password not verified yet) | Common MySQL statements; MySQL-only syntax may need changes |
| **Oracle (TNS)** | 1521 | `--enable-oracle` | any user, `HELIOSDB_ORACLE_NATIVE_PASSWORD` | Core DDL, DML and common queries run unchanged; Oracle-specific syntax and PL/SQL need rewriting ([in-house applications](/docs/full/reference/protocols/oracle/inhouse_application_compatibility/)) |
| **MongoDB** | 27017 | `--enable-mongodb` | `HELIOSDB_MONGODB_USER` / `HELIOSDB_MONGODB_PASSWORD` (SCRAM-SHA-256) | Connects and authenticates; reads and writes of HeliosDB tables are planned (queries return no documents today); see the [compatibility notes](/docs/full/guides/mongodb_migration/#compatibility-notes) |
| **Cassandra (CQL)** | 9042 | `--enable-cassandra` | `HELIOSDB_CASSANDRA_USER` / `HELIOSDB_CASSANDRA_PASSWORD` | Accepts and authenticates CQL connections; reads and writes of HeliosDB tables, and connections from standard drivers (DataStax drivers, `cqlsh`), are planned; see the [compatibility notes](/docs/full/guides/cassandra_migration/#compatibility-notes) |
| **Redis** | 6379 | `--enable-redis` | `AUTH <role> <password>` (role name checked, password not verified yet) | In-memory keyspace, not persisted to HeliosDB tables; see [redis](/docs/full/reference/protocols/redis/) |
| **SQL Server (TDS)** | 1433 | `--enable-sqlserver` | `HELIOSDB_SQLSERVER_USER` / `HELIOSDB_SQLSERVER_PASSWORD` | Connects and authenticates; reads and writes of HeliosDB tables are planned |

Every port has a flag and an environment variable (`--mysql-port` /
`HELIOSDB_MYSQL_PORT` and so on). All listeners bind `--bind-addr` (default
`127.0.0.1`); a non-loopback address also needs `--allow-external`. HeliosDB Full
listeners do not terminate TLS; put a TLS-terminating proxy in front. Native
PostgreSQL TLS (`--tls-cert`, `--tls-key`, `--tls-require`), with post-quantum key
exchange preferred, is planned for the next release. See
[Connecting](/docs/full/guides/user/connecting/) and the
[Server Configuration Reference](/docs/full/reference/configuration/).

### Interface pages without a listener in `heliosdb-full`

The GraphQL, Snowflake, ClickHouse, DRDA (DB2) and Pinecone pages in this section
describe compatibility layers that are planned and not served by the `heliosdb-full`
server: it opens no listener for them, and the HTTP gateway answers `/snowflake/`,
`/dbsql/` and `/pinecone/` paths with `501 Not Implemented`. Reach the same data over
the PostgreSQL listener or `POST /api/v1/query`.

- **S3-compatible object API: planned; no listener in `heliosdb-full`.** An
  S3-compatible object API for HeliosDB Full is on the roadmap and is not part of the current release. The bucket-management SQL statements described in earlier release
  notes are planned together with it; do not rely on them for retention or legal
  hold.

---

## Connection examples

Start the server with the listeners you need (PostgreSQL and HTTP are on by default),
for example `heliosdb-full --data-dir ./data --enable-mysql --enable-oracle --enable-mongodb`.
The examples read passwords from the environment; never put them on the command line.

### PostgreSQL (port 5432)

```python
import os, psycopg

conn = psycopg.connect(host="127.0.0.1", port=5432, dbname="postgres",
                       user="postgres", password=os.environ["HELIOSDB_SUPERUSER_PASSWORD"])
print(conn.execute("SELECT version()").fetchone()[0])
```

### MySQL (port 3306, `--enable-mysql`)

```python
import os, pymysql

conn = pymysql.connect(host="127.0.0.1", port=3306, database="postgres",
                       user="app", password=os.environ["APP_PASSWORD"])
```

Log on with a role created over PostgreSQL (`CREATE ROLE app LOGIN PASSWORD '...'`).
The MySQL listener does not verify passwords yet and has no TLS; keep it on a trusted
network (see [MySQL configuration](/docs/full/reference/protocols/mysql/configuration/)).

### Oracle (port 1521, `--enable-oracle`)

```python
import os, oracledb   # python-oracledb in thin mode

conn = oracledb.connect(user="app", password=os.environ["HELIOSDB_ORACLE_NATIVE_PASSWORD"],
                        dsn="127.0.0.1:1521/heliosdb")
conn.autocommit = True
```

### MongoDB (port 27017, `--enable-mongodb`)

```python
import os
from pymongo import MongoClient

client = MongoClient("mongodb://127.0.0.1:27017/",
                     username=os.environ["HELIOSDB_MONGODB_USER"],
                     password=os.environ["HELIOSDB_MONGODB_PASSWORD"],
                     authMechanism="SCRAM-SHA-256")
```

### Cassandra CQL (port 9042, `--enable-cassandra`)

Standard Cassandra drivers (the DataStax drivers and `cqlsh`, which is built on the
DataStax Python driver) cannot connect to the listener yet; support for them
is planned, together with reading and writing HeliosDB tables over CQL. The
listener accepts and authenticates CQL native-protocol connections with
`HELIOSDB_CASSANDRA_USER` / `HELIOSDB_CASSANDRA_PASSWORD`.

### Redis (port 6379, `--enable-redis`)

```python
import redis

client = redis.Redis(host="127.0.0.1", port=6379, username="app", password="unused")
```

The Redis listener requires `AUTH` with a role name from the role catalog; it does not
verify the password yet, so keep it on a trusted network.

### HTTP gateway (port 8443, plain HTTP)

```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 * FROM users LIMIT 10"}'
```

See the [HTTP/REST API reference](/docs/full/reference/api/http_rest_api/).

---

## Cross-Protocol Resources

| Resource | Description |
|----------|-------------|
| [PROTOCOL_COMPATIBILITY_MATRIX.md](https://www.heliosdb.com/docs/full/reference/protocols/protocol_compatibility_matrix/) | Unified compatibility overview for all protocols |
| [MIGRATION_GUIDE.md](https://www.heliosdb.com/docs/full/reference/protocols/migration_guide/) | General database migration strategies |

---

## Migration Guides

| Source Database | Migration Guide |
|-----------------|-----------------|
| MySQL | [migrations/MIGRATION_FROM_MYSQL_TO_HELIOSDB.md](https://www.heliosdb.com/docs/full/reference/protocols/migrations/migration_from_mysql_to_heliosdb/) |
| SQL Server | [migrations/MIGRATION_FROM_MSSQL_TO_HELIOSDB.md](https://www.heliosdb.com/docs/full/reference/protocols/migrations/migration_from_mssql_to_heliosdb/) |
| SQLite | [migrations/MIGRATION_FROM_SQLITE_TO_HELIOSDB.md](https://www.heliosdb.com/docs/full/reference/protocols/migrations/migration_from_sqlite_to_heliosdb/) |

---

## Driver Compatibility Matrix

| Driver | PostgreSQL | MySQL | MongoDB | Cassandra | Redis |
|--------|:----------:|:-----:|:-------:|:---------:|:-----:|
| **Python** | psycopg2/3 | mysql-connector | PyMongo | cassandra-driver | redis-py |
| **Node.js** | node-postgres | mysql2 | mongodb | cassandra-driver | ioredis |
| **Java** | JDBC | JDBC | MongoDB Driver | DataStax | Jedis |
| **Go** | lib/pq | go-sql-driver | mongo-go | gocql | go-redis |
| **Rust** | rust-postgres | mysql | mongodb | - | redis-rs |
| **C#** | Npgsql | MySqlConnector | MongoDB.Driver | CassandraCSharpDriver | StackExchange.Redis |

MongoDB drivers: connection and authentication only, for now; reading and writing
HeliosDB tables through them is planned. Cassandra drivers: the standard drivers
listed above cannot connect to the listener yet; support for them, and CQL
reads and writes of HeliosDB tables, are planned. Redis drivers reach the listener's
in-memory keyspace, which is not persisted.

---

## Choosing a protocol

- **PostgreSQL**: the primary interface, with SCRAM authentication and the widest
  SQL coverage (native TLS is planned for the next release). Use it for new applications and for anything exposed beyond a
  trusted network.
- **MySQL, Oracle, SQL Server**: keep an existing application's driver while you move
  its data to HeliosDB; check each protocol's compatibility page for the statements
  your code uses.
- **MongoDB and Cassandra**: the listeners accept and authenticate connections;
  reading and writing HeliosDB tables through them is planned, as is connecting
  with the DataStax drivers.
- **Redis**: key-value access in an in-memory keyspace that is not persisted.
- **HTTP gateway**: scripts, serverless functions and tools that cannot load a
  database driver.