Connecting to HeliosDB

This guide covers all the ways to connect to HeliosDB using different protocols, programming languages, and tools.

---

Table of Contents

1. Connection Protocols
2. Command-Line Clients
3. Programming Languages
4. GUI Tools
5. Connection Pooling
6. Security & Authentication
7. Troubleshooting

---

Connection Protocols

HeliosDB Full serves several wire protocols from one server; all of them read and write the same tables.

Protocol	Default port	Enabled by default	Clients
PostgreSQL	5432	Yes (--no-postgres disables)	psql, pgAdmin, DBeaver, psycopg, pgx, JDBC, any PostgreSQL driver
HTTP gateway	8443	Yes (--no-http disables)	curl, any HTTP client (POST /api/v1/query)
MySQL	3306	No (--enable-mysql)	mysql CLI, PyMySQL, MySQL Connector/J
Oracle (TNS)	1521	No (--enable-oracle)	Oracle thin clients (tested with python-oracledb thin mode)
SQL Server (TDS)	1433	No (--enable-sqlserver)	sqlcmd, TDS drivers
MongoDB	27017	No (--enable-mongodb)	mongosh, MongoDB drivers
Cassandra (CQL)	9042	No (--enable-cassandra)	cqlsh, CQL drivers
Redis	6379	No (--enable-redis)	redis-cli, Redis clients

Each port has a flag and an environment variable: --postgres-port (HELIOSDB_POSTGRES_PORT), --http-port (HELIOSDB_HTTP_PORT), --mysql-port (HELIOSDB_MYSQL_PORT), --oracle-port (HELIOSDB_ORACLE_PORT), --sqlserver-port, --mongodb-port, --cassandra-port, --redis-port (with matching HELIOSDB_*_PORT variables). All listeners bind --bind-addr (default 127.0.0.1); any other address also needs --allow-external.

Credentials per listener

Listener	User	Password	Notes
PostgreSQL	postgres, or a role from CREATE ROLE ... LOGIN PASSWORD	HELIOSDB_SUPERUSER_PASSWORD, or the role’s password	SCRAM-SHA-256
MySQL	a role from the role catalog (same roles as PostgreSQL)	see the warning below	caching_sha2_password or mysql_native_password; the user name is checked, the password is not yet verified
Oracle	any user name	HELIOSDB_ORACLE_NATIVE_PASSWORD; if it is unset, the password is the user name (for example scott/scott), so always set it	O5LOGON; one password for the listener
SQL Server	HELIOSDB_SQLSERVER_USER	HELIOSDB_SQLSERVER_PASSWORD	Logins denied until both are set
MongoDB	HELIOSDB_MONGODB_USER	HELIOSDB_MONGODB_PASSWORD	Logins denied until both are set
Cassandra	HELIOSDB_CASSANDRA_USER	HELIOSDB_CASSANDRA_PASSWORD	Logins denied until both are set
Redis	AUTH <role> <password>	not verified yet	the role name must exist in the role catalog; keep the listener on a trusted network
HTTP	—	HELIOSDB_API_KEY (Authorization: Bearer or X-API-Key)	Health and status routes need no key

MySQL and Redis listeners: passwords are not verified yet

In the current release the MySQL listener checks that the user name exists in the role catalog and that the client sent a non-empty password, but it does not verify the password itself: any non-empty password is accepted for an existing role (including postgres). The Redis listener likewise accepts AUTH for any existing role name without checking the password. Enable --enable-mysql and --enable-redis only on a loopback address or a private network where every client is trusted, and use the PostgreSQL listener for anything that needs real authentication. Empty MySQL passwords are rejected.

If HELIOSDB_SUPERUSER_PASSWORD is not set, the server generates a password for postgres and prints it once in its log. --auth-mode trust (no credentials) is accepted only when the server is bound to a loopback address.

TLS

TLS: planned

HeliosDB Full listeners do not terminate TLS; put a TLS-terminating proxy in front. Native PostgreSQL TLS (with post-quantum key exchange preferred) is planned; the --tls-cert, --tls-key and --tls-require flags in this section describe that planned feature.

The PostgreSQL listener supports TLS: --tls-cert, --tls-key and, to refuse plaintext sessions, --tls-require. The other listeners and the HTTP gateway are plaintext; keep them on a private network or put a TLS proxy in front.

Example: enable PostgreSQL, MySQL and Oracle for a private network

export HELIOSDB_SUPERUSER_PASSWORD=...          # from your secrets store
export HELIOSDB_ORACLE_NATIVE_PASSWORD=...
heliosdb-full --data-dir /var/lib/heliosdb \
  --bind-addr 10.0.0.12 --allow-external \
  --tls-cert /etc/heliosdb/tls/server.crt --tls-key /etc/heliosdb/tls/server.key \
  --enable-mysql --enable-oracle

HeliosDB Full has no gRPC client API: application code connects over one of the protocols above. Every flag is described in the Server Configuration Reference.

---

Command-Line Clients

1. psql (PostgreSQL Client) (Recommended)

HeliosDB Full speaks the PostgreSQL wire protocol, so the standard psql client works directly.

# Install (if not already installed)
sudo apt install postgresql-client     # Ubuntu/Debian
brew install libpq                     # macOS

# Connect as the built-in superuser
psql -h localhost -p 5432 -U postgres -d postgres

# Password from the environment (avoid it on the command line)
PGPASSWORD="$HELIOSDB_SUPERUSER_PASSWORD" psql -h localhost -U postgres

# Connection string with an application role
psql "postgresql://app@localhost:5432/postgres"

# With TLS (server started with --tls-cert/--tls-key)
psql "postgresql://app@db.internal:5432/postgres?sslmode=verify-full&sslrootcert=/path/to/ca.crt"

Useful psql commands:

\dt                 -- List tables
\d users            -- Describe table
\du                 -- List roles
\timing on          -- Show query execution time
\x on               -- Expanded display
\q                  -- Quit

HeliosDB-specific status statements such as SHOW SERVER STATUS, SHOW PROTOCOLS and SHOW CONNECTIONS also work from psql.

2. mysql CLI

Start the server with --enable-mysql, then connect with a role from the role catalog (for example postgres, or a role you created). The listener does not verify MySQL passwords yet (see Credentials per listener), so keep it on a trusted network:

# Install
sudo apt install mysql-client

# Connect
mysql -h localhost -P 3306 -u postgres -p postgres

# Connection parameters
mysql --host=localhost --port=3306 --user=app --password --database=postgres

import os, pymysql

conn = pymysql.connect(host="localhost", port=3306, user="app",
                       password=os.environ["APP_PASSWORD"], database="postgres")
with conn.cursor() as cur:
    cur.execute("SELECT name FROM users WHERE id = %s", (1,))
    print(cur.fetchall())
conn.commit()

The MySQL listener runs SQL on the same engine as the PostgreSQL listener; MySQL-only functions and syntax may need small changes.

3. Oracle clients

Start the server with --enable-oracle and set HELIOSDB_ORACLE_NATIVE_PASSWORD. Clients log on with any user name and that password; the service name is not checked.

import os, oracledb   # python-oracledb, thin mode

conn = oracledb.connect(user="app", password=os.environ["HELIOSDB_ORACLE_NATIVE_PASSWORD"],
                        dsn="localhost:1521/heliosdb")
conn.autocommit = True
cur = conn.cursor()
cur.execute("SELECT name FROM users WHERE id = :id", id=1)
print(cur.fetchall())

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

Statements run on the same SQL engine as the PostgreSQL listener, without Oracle dialect translation, and each statement commits as it runs. Driver commit()/rollback() calls are not supported yet, so enable autocommit, and open a new cursor for each statement. See the Oracle Quick Start for what runs over the Oracle listener today.

---

Programming Languages

Python

Install Client

HeliosDB Full speaks the PostgreSQL wire protocol, so use a standard PostgreSQL driver such as psycopg:

pip install "psycopg[binary]"

# Or the older psycopg2 driver
pip install psycopg2-binary

Synchronous Connection (psycopg 3)

import psycopg

with psycopg.connect(
    host="localhost",
    port=5432,
    user="app",
    password="mysecretpassword",
    dbname="myapp",
) as conn:
    rows = conn.execute("SELECT * FROM users WHERE id = %s", (1,)).fetchall()
    for row in rows:
        print(row)
# Connection closed (and the transaction committed) on exit

Async Connection (psycopg 3)

import asyncio
import psycopg

async def main():
    async with await psycopg.AsyncConnection.connect(
        "postgresql://app:mysecretpassword@localhost:5432/myapp"
    ) as conn:
        cur = await conn.execute("SELECT * FROM users LIMIT 10")
        async for row in cur:
            print(row)

asyncio.run(main())

Using psycopg2 (PostgreSQL Driver)

import psycopg2

# Connect
conn = psycopg2.connect(
    host="localhost",
    port=5432,
    user="app",
    password="mysecretpassword",
    database="myapp"
)

# Create cursor
cur = conn.cursor()

# Execute query
cur.execute("SELECT * FROM users WHERE email = %s", ("alice@example.com",))

# Fetch results
rows = cur.fetchall()
for row in rows:
    print(row)

# Commit transaction
conn.commit()

# Close
cur.close()
conn.close()

JavaScript/TypeScript

Install Client

HeliosDB Full speaks the PostgreSQL wire protocol, so use the standard node-postgres driver. (There is no HeliosDB package on npm — the unrelated heliosdb npm package is not ours.)

npm install pg

# Or with TypeScript types
npm install pg @types/pg

Node.js Connection

const { Client } = require('pg');

// Create client
const client = new Client({
  host: 'localhost',
  port: 5432,
  user: 'app',
  password: 'mysecretpassword',
  database: 'myapp'
});

// Connect
await client.connect();

// Execute query
const result = await client.query('SELECT * FROM users WHERE id = $1', [1]);

console.log(result.rows);

// Close
await client.end();

TypeScript with Type Safety

import { Client, QueryResult } from 'pg';

interface User {
  id: number;
  username: string;
  email: string;
  created_at: Date;
}

const client = new Client({
  host: 'localhost',
  port: 5432,
  user: 'app',
  password: 'mysecretpassword',
  database: 'myapp'
});

await client.connect();

const result: QueryResult<User> = await client.query<User>(
  'SELECT * FROM users WHERE id = $1',
  [1]
);

result.rows.forEach((user: User) => {
  console.log(`${user.username}: ${user.email}`);
});

await client.end();

Connection Pooling with node-postgres

const { Pool } = require('pg');

const pool = new Pool({
  host: 'localhost',
  port: 5432,
  user: 'app',
  password: 'mysecretpassword',
  database: 'myapp',
  max: 20, // Connection pool size
  idleTimeoutMillis: 30000
});

// Execute query
const result = await pool.query('SELECT * FROM users WHERE email = $1', ['alice@example.com']);

console.log(result.rows);

Java

Add Maven Dependency

Use the standard PostgreSQL JDBC driver (HeliosDB Full speaks the PostgreSQL wire protocol):

<dependency>
    <groupId>org.postgresql</groupId>
    <artifactId>postgresql</artifactId>
    <version>42.6.0</version>
</dependency>

JDBC Connection

import java.sql.*;

public class HeliosDBExample {
    public static void main(String[] args) {
        String url = "jdbc:postgresql://localhost:5432/myapp";
        String user = "app";
        String password = "mysecretpassword";

        try (Connection conn = DriverManager.getConnection(url, user, password)) {
            System.out.println("Connected to HeliosDB!");

            // Execute query
            String sql = "SELECT * FROM users WHERE id = ?";
            PreparedStatement pstmt = conn.prepareStatement(sql);
            pstmt.setInt(1, 1);

            ResultSet rs = pstmt.executeQuery();

            while (rs.next()) {
                System.out.println("User: " + rs.getString("username"));
                System.out.println("Email: " + rs.getString("email"));
            }

            rs.close();
            pstmt.close();

        } catch (SQLException e) {
            System.err.println("Connection failed: " + e.getMessage());
        }
    }
}

Spring Boot Configuration

application.yml

spring:
  datasource:
    url: jdbc:postgresql://localhost:5432/myapp
    username: app
    password: mysecretpassword
    driver-class-name: org.postgresql.Driver
    hikari:
      maximum-pool-size: 20
      minimum-idle: 5
      connection-timeout: 30000

Go

HeliosDB Full speaks the PostgreSQL wire protocol, so any standard Go PostgreSQL driver works. The example below uses pgx. (The Go REST client in HeliosDB-SDKs/sdks/go is for HeliosDB Nano and Lite. It calls /v1/... endpoints that Full does not serve, so it does not work with Full.)

Install Module

go get github.com/jackc/pgx/v5

Connection Example

package main

import (
    "context"
    "fmt"
    "log"

    "github.com/jackc/pgx/v5"
)

func main() {
    ctx := context.Background()
    conn, err := pgx.Connect(ctx, "postgres://app:mysecretpassword@localhost:5432/myapp")
    if err != nil {
        log.Fatal(err)
    }
    defer conn.Close(ctx)

    rows, err := conn.Query(ctx, "SELECT id, username, email FROM users WHERE id = $1", 1)
    if err != nil {
        log.Fatal(err)
    }
    defer rows.Close()

    for rows.Next() {
        var id int
        var username, email string
        if err := rows.Scan(&id, &username, &email); err != nil {
            log.Fatal(err)
        }
        fmt.Printf("User: %s (%s)\n", username, email)
    }
}

Rust

Use a standard PostgreSQL driver such as tokio-postgres over the PostgreSQL listener.

Add Dependency

[dependencies]
tokio-postgres = "0.7"
tokio = { version = "1", features = ["full"] }

Connection Example

use tokio_postgres::{Error, NoTls};

#[tokio::main]
async fn main() -> Result<(), Error> {
    // Connect over the PostgreSQL listener
    let (client, connection) = tokio_postgres::connect(
        "host=localhost port=5432 user=app password=mysecretpassword dbname=myapp",
        NoTls,
    )
    .await?;
    tokio::spawn(async move {
        if let Err(e) = connection.await {
            eprintln!("connection error: {e}");
        }
    });

    // Execute query
    let rows = client
        .query("SELECT username, email FROM users WHERE id = $1", &[&1i32])
        .await?;

    // Process results
    for row in rows {
        let username: String = row.get("username");
        let email: String = row.get("email");
        println!("User: {} ({})", username, email);
    }

    Ok(())
}

---

GUI Tools

1. pgAdmin (PostgreSQL Admin Tool)

Works with HeliosDB via PostgreSQL protocol

1. Download from https://www.pgadmin.org/
2. Add new server:
   • Host: localhost
   • Port: 5432
   • Username: postgres (or your application role)
   • Password: (your password)

2. DBeaver (Universal Database Tool)

Cross-platform, supports multiple databases

1. Download from https://dbeaver.io/
2. Create new connection → PostgreSQL
3. Enter connection details

3. DataGrip (JetBrains IDE)

Professional database IDE

1. File → New → Data Source → PostgreSQL
2. Configure connection
3. Test connection

---

Connection Pooling

Why Use Connection Pooling?

• Reduce connection overhead: Reuse existing connections
• Better concurrency: Handle more simultaneous requests
• Resource management: Limit total connections

Python Connection Pooling

# pip install "psycopg[binary,pool]"
from psycopg_pool import ConnectionPool

# Create pool
pool = ConnectionPool(
    "host=localhost dbname=myapp user=app password=password",
    min_size=10,      # Minimum connections
    max_size=100,     # Maximum connections
    timeout=30.0      # Seconds to wait for a free connection
)

# Borrow a connection from the pool
with pool.connection() as conn:
    rows = conn.execute("SELECT * FROM users").fetchall()
    print(rows)

# Connection automatically returned to pool

Node.js Connection Pooling

const { Pool } = require('pg');

const pool = new Pool({
  host: 'localhost',
  port: 5432,
  user: 'app',
  password: 'mysecretpassword',
  database: 'myapp',
  max: 20,                    // Max connections
  min: 5,                     // Min connections
  idleTimeoutMillis: 30000,   // Close idle connections after 30s
  connectionTimeoutMillis: 2000
});

// Use pool
pool.query('SELECT * FROM users', (err, res) => {
  if (err) throw err;
  console.log(res.rows);
});

Java Connection Pooling (HikariCP)

import com.zaxxer.hikari.HikariConfig;
import com.zaxxer.hikari.HikariDataSource;

public class DatabasePool {
    private static HikariDataSource dataSource;

    static {
        HikariConfig config = new HikariConfig();
        config.setJdbcUrl("jdbc:postgresql://localhost:5432/myapp");
        config.setUsername("app");
        config.setPassword("mysecretpassword");
        config.setMaximumPoolSize(20);
        config.setMinimumIdle(5);
        config.setConnectionTimeout(30000);

        dataSource = new HikariDataSource(config);
    }

    public static Connection getConnection() throws SQLException {
        return dataSource.getConnection();
    }
}

---

Security & Authentication

Password authentication

PostgreSQL and MySQL logins use roles:

-- as postgres
CREATE ROLE app LOGIN PASSWORD 'a-long-random-password' CONNECTION LIMIT 50;
ALTER ROLE app PASSWORD 'rotated-password';
ALTER ROLE app NOLOGIN;

Clients can read the password from the environment instead of the command line:

export PGPASSWORD="$APP_PASSWORD"
psql -h db.internal -U app -d postgres

In the current release every role that can log in can read and write all data (GRANT/REVOKE return SQLSTATE 0A000); use separate server instances for data that must be isolated.

SSL/TLS encryption

Start the server with --tls-cert and --tls-key (and --tls-require to refuse plaintext), then:

psql "postgresql://app@db.internal/postgres?sslmode=require"
psql "postgresql://app@db.internal/postgres?sslmode=verify-full&sslrootcert=/path/to/ca.crt"

import psycopg
conn = psycopg.connect(host="db.internal", user="app", password=password, dbname="postgres",
                       sslmode="verify-full", sslrootcert="/path/to/ca.crt")

SHOW CERTIFICATES reports whether TLS is configured and whether the current session is encrypted. Client-certificate (mTLS), LDAP and OAuth logins are not offered by the server; put a proxy that provides them in front if you need them.

---

Troubleshooting

Connection refused

# 1. Is the server running, and which listeners did it open?
journalctl -u heliosdb | grep "listening on"     # or: docker logs heliosdb
# 2. Is the port listening on the address you connect to?
ss -ltnp | grep -E ":(5432|3306|1521|8443) "
# 3. Firewall / published container ports
docker port heliosdb

Listeners other than PostgreSQL and HTTP need --enable-<protocol>. Remote clients need --bind-addr <address> --allow-external.

Authentication failed

1. PostgreSQL/MySQL: user postgres with HELIOSDB_SUPERUSER_PASSWORD, or a role with LOGIN and a password. VALID UNTIL in the past and a reached CONNECTION LIMIT refuse logins; check with SHOW ROLES.
2. Oracle: the password is HELIOSDB_ORACLE_NATIVE_PASSWORD.
3. SQL Server, MongoDB, Cassandra: both HELIOSDB_<PROTOCOL>_USER and _PASSWORD must be set on the server.
4. With --tls-require, PostgreSQL clients must use sslmode=require or stricter.

Timeout errors

The server closes connections that do not finish the handshake within --startup-timeout-secs (default 30). For long statements, raise statement_timeout for the session; on the client side set a connect timeout, for example connect_timeout=10 in the connection string.

SSL certificate errors

# Verify against your CA (recommended)
psql "postgresql://app@db.internal/postgres?sslmode=verify-full&sslrootcert=/path/to/ca.crt"
# Encrypt without verification (testing only)
psql "postgresql://app@db.internal/postgres?sslmode=require"

The certificate’s subject alternative name must match the host name clients use.

---

Connection String Format

PostgreSQL DSN Format

postgresql://[user[:password]@][host][:port][/dbname][?param1=value1&...]

Examples:

# Basic
postgresql://app@localhost/postgres

# With password
postgresql://app:password@localhost:5432/postgres

# With SSL
postgresql://app@localhost/postgres?sslmode=require

# With multiple parameters
postgresql://app@localhost/postgres?sslmode=require&connect_timeout=30&application_name=myapp

---

Next: Querying Data →