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
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)
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
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
Redis	6379	`--enable-redis`	`AUTH <role> <password>` (role name checked, password not verified yet)	In-memory keyspace, not persisted to HeliosDB tables; see 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 and the Server Configuration Reference.

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)

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`)

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).

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

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`)

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`)

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)

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.

Cross-Protocol Resources

Resource	Description
PROTOCOL_COMPATIBILITY_MATRIX.md	Unified compatibility overview for all protocols
MIGRATION_GUIDE.md	General database migration strategies

Migration Guides

Source Database	Migration Guide
MySQL	migrations/MIGRATION_FROM_MYSQL_TO_HELIOSDB.md
SQL Server	migrations/MIGRATION_FROM_MSSQL_TO_HELIOSDB.md
SQLite	migrations/MIGRATION_FROM_SQLITE_TO_HELIOSDB.md

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.

HeliosDB Protocol Documentation Hub

Listeners served by heliosdb-full

Interface pages without a listener in heliosdb-full