Connecting to HeliosDB

Last Updated: November 1, 2025 Version: v6.0 Phase 2 M1

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 supports multiple wire protocols for maximum compatibility:

Protocol	Port	Use Case	Compatibility
PostgreSQL	5432	Default, broad tool support	psql, pgAdmin, Postico, etc.
MySQL	3306	MySQL client compatibility	mysql CLI, MySQL Workbench
gRPC	50051	High-performance, low-latency	Custom clients, microservices
HTTP/REST	8080	Web apps, serverless	curl, Postman, browsers
WebSocket	8081	Real-time streaming	JavaScript clients, dashboards

---

Command-Line Clients

1. HeliosDB Native CLI (Recommended)

Best autocomplete, syntax highlighting, and HeliosDB-specific features

# Install
cargo install heliosdb-cli

# Connect
heliosdb cli connect \
  --host localhost \
  --port 5432 \
  --username helios \
  --database myapp

# With password from environment
export HELIOSDB_PASSWORD=mysecretpassword
heliosdb cli connect --host localhost --username helios

# Connection string format
heliosdb cli connect postgresql://helios:password@localhost:5432/myapp

Features: - Tab completion for SQL keywords, table names, column names - Syntax highlighting - Query history (↑/↓ arrows) - Multi-line editing - JSON formatting - Performance metrics display

Example session:

heliosdb> \c myapp
Connected to database "myapp"

heliosdb> SELECT * FROM users WHERE id = 1;
 id | username | email              | created_at
----+----------+--------------------+-------------------------
  1 | alice    | alice@example.com  | 2025-11-01 10:30:00

Query time: 2.3ms
Rows returned: 1

heliosdb> \dt
          List of relations
 Schema |  Name  |  Type  | Owner
--------+--------+--------+-------
 public | users  | table  | helios
 public | posts  | table  | helios

2. psql (PostgreSQL Client)

Most widely used, excellent compatibility

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

# macOS
brew install libpq

# Connect
psql -h localhost -p 5432 -U helios -d myapp

# With password inline (not recommended for production)
PGPASSWORD=mysecretpassword psql -h localhost -U helios -d myapp

# Connection string
psql postgresql://helios:password@localhost:5432/myapp

# With SSL/TLS
psql "postgresql://helios@localhost:5432/myapp?sslmode=require"

Useful psql commands:

\l                  -- List databases
\c myapp            -- Connect to database
\dt                 -- List tables
\d users            -- Describe table
\di                 -- List indexes
\df                 -- List functions
\dv                 -- List views
\du                 -- List users
\q                  -- Quit

\timing on          -- Show query execution time
\x on               -- Expanded display (vertical format)
\o output.txt       -- Write output to file

3. mysql CLI

For users familiar with MySQL

# Install
sudo apt install mysql-client

# Connect
mysql -h localhost -P 3306 -u helios -p myapp

# Connection parameters
mysql \
  --host=localhost \
  --port=3306 \
  --user=helios \
  --password=mysecretpassword \
  --database=myapp

Note: HeliosDB's MySQL protocol emulation supports most MySQL features, but some advanced MySQL-specific functions may behave differently.

---

Programming Languages

Python

Install Client

pip install heliosdb-py

# Or with async support
pip install heliosdb-py[async]

Synchronous Connection

from heliosdb import HeliosClient

# Create client
client = HeliosClient(
    host="localhost",
    port=5432,
    user="helios",
    password="mysecretpassword",
    database="myapp"
)

# Connect
client.connect()

# Execute query
result = client.execute("SELECT * FROM users WHERE id = %s", [1])

# Access results
for row in result.rows:
    print(f"User: {row['username']}, Email: {row['email']}")

# Close connection
client.close()

Async Connection (High Performance)

import asyncio
from heliosdb.aio import AsyncHeliosClient

async def main():
    # Create async client
    client = AsyncHeliosClient(
        host="localhost",
        port=5432,
        user="helios",
        password="mysecretpassword",
        database="myapp"
    )

    # Connect
    await client.connect()

    # Execute query
    result = await client.execute("SELECT * FROM users LIMIT 10")

    # Process results
    async for row in result:
        print(row)

    # Close
    await client.close()

asyncio.run(main())

Context Manager (Automatic Cleanup)

from heliosdb import HeliosClient

with HeliosClient.connect("postgresql://helios:password@localhost/myapp") as client:
    result = client.execute("SELECT COUNT(*) FROM users")
    print(f"Total users: {result.scalar()}")
# Connection automatically closed

Using psycopg2 (PostgreSQL Driver)

import psycopg2

# Connect
conn = psycopg2.connect(
    host="localhost",
    port=5432,
    user="helios",
    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

npm install heliosdb

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

Node.js Connection

const { HeliosClient } = require('heliosdb');

// Create client
const client = new HeliosClient({
  host: 'localhost',
  port: 5432,
  user: 'helios',
  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 { HeliosClient, QueryResult } from 'heliosdb';

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

const client = new HeliosClient<User>({
  host: 'localhost',
  port: 5432,
  user: 'helios',
  password: 'mysecretpassword',
  database: 'myapp'
});

await client.connect();

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

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

await client.end();

Using node-postgres (pg)

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

const pool = new Pool({
  host: 'localhost',
  port: 5432,
  user: 'helios',
  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

<dependency>
    <groupId>com.heliosdb</groupId>
    <artifactId>heliosdb-jdbc</artifactId>
    <version>6.0.0</version>
</dependency>

<!-- Or use PostgreSQL JDBC driver -->
<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 = "helios";
        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: helios
    password: mysecretpassword
    driver-class-name: org.postgresql.Driver
    hikari:
      maximum-pool-size: 20
      minimum-idle: 5
      connection-timeout: 30000

Go

Install Module

go get github.com/heliosdb/heliosdb-go

Connection Example

package main

import (
    "context"
    "fmt"
    "log"

    "github.com/heliosdb/heliosdb-go"
)

func main() {
    // Create client
    client := heliosdb.NewClient(&heliosdb.Config{
        Host:     "localhost",
        Port:     5432,
        User:     "helios",
        Password: "mysecretpassword",
        Database: "myapp",
    })

    // Connect
    ctx := context.Background()
    if err := client.Connect(ctx); err != nil {
        log.Fatal(err)
    }
    defer client.Close()

    // Execute query
    rows, err := client.Query(ctx, "SELECT * FROM users WHERE id = $1", 1)
    if err != nil {
        log.Fatal(err)
    }
    defer rows.Close()

    // Process results
    for rows.Next() {
        var id int
        var username, email string
        var createdAt time.Time

        if err := rows.Scan(&id, &username, &email, &createdAt); err != nil {
            log.Fatal(err)
        }

        fmt.Printf("User: %s (%s)\n", username, email)
    }
}

Rust

Add Dependency

[dependencies]
heliosdb = "0.6.0"
tokio = { version = "1.35", features = ["full"] }

Connection Example

use heliosdb::{Client, Error};

#[tokio::main]
async fn main() -> Result<(), Error> {
    // Create client
    let client = Client::builder()
        .host("localhost")
        .port(5432)
        .user("helios")
        .password("mysecretpassword")
        .database("myapp")
        .build()
        .await?;

    // Execute query
    let rows = client
        .query("SELECT * FROM users WHERE id = $1", &[&1])
        .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. HeliosDB Studio (Official GUI)

Native desktop application for HeliosDB

# Download from releases
curl -LO https://github.com/heliosdb/heliosdb-studio/releases/latest/download/heliosdb-studio-linux-x64.AppImage

# Run
chmod +x heliosdb-studio-linux-x64.AppImage
./heliosdb-studio-linux-x64.AppImage

Features: - Visual query builder - Schema designer - Performance monitoring - Query profiling - Data export/import

2. pgAdmin (PostgreSQL Admin Tool)

Works with HeliosDB via PostgreSQL protocol

1. Download from https://www.pgadmin.org/
2. Add new server:
3. Host: localhost
4. Port: 5432
5. Username: helios
6. Password: (your password)

3. DBeaver (Universal Database Tool)

Cross-platform, supports multiple databases

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

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

from heliosdb.pool import ConnectionPool

# Create pool
pool = ConnectionPool(
    dsn="postgresql://helios:password@localhost/myapp",
    min_size=10,      # Minimum connections
    max_size=100,     # Maximum connections
    timeout=30.0      # Connection timeout (seconds)
)

# Acquire connection from pool
async with pool.acquire() as conn:
    result = await conn.execute("SELECT * FROM users")
    print(result.rows)

# Connection automatically returned to pool

Node.js Connection Pooling

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

const pool = new Pool({
  host: 'localhost',
  port: 5432,
  user: 'helios',
  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("helios");
        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

Basic username/password (default):

# Set password in environment
export HELIOSDB_PASSWORD=mysecretpassword

# Connect without entering password
psql -h localhost -U helios -d myapp

SSL/TLS Encryption

Encrypt connections in transit:

# Require SSL
psql "postgresql://helios@localhost/myapp?sslmode=require"

# Verify server certificate
psql "postgresql://helios@localhost/myapp?sslmode=verify-full&sslrootcert=/path/to/ca.crt"

Python with SSL:

client = HeliosClient(
    host="localhost",
    port=5432,
    user="helios",
    password="password",
    database="myapp",
    sslmode="require",
    sslrootcert="/path/to/ca.crt"
)

Certificate Authentication (mTLS)

Use client certificates instead of passwords:

psql "postgresql://helios@localhost/myapp?sslmode=require&sslcert=/path/to/client.crt&sslkey=/path/to/client.key&sslrootcert=/path/to/ca.crt"

LDAP/Active Directory

Enterprise authentication:

Configure in heliosdb.conf:

[auth]
method = "ldap"
ldap_server = "ldap://ldap.example.com"
ldap_base_dn = "ou=users,dc=example,dc=com"
ldap_bind_dn = "cn=admin,dc=example,dc=com"
ldap_bind_password = "admin_password"

OAuth2/OIDC

Use existing identity providers:

from heliosdb import HeliosClient

client = HeliosClient.from_oauth(
    host="localhost",
    port=5432,
    oauth_provider="https://accounts.google.com",
    oauth_client_id="your-client-id",
    oauth_client_secret="your-secret"
)

---

Troubleshooting

Connection Refused

Error: could not connect to server: Connection refused

Solutions:

# 1. Check if server is running
sudo systemctl status heliosdb
ps aux | grep heliosdb

# 2. Check if port is listening
sudo netstat -tlnp | grep 5432

# 3. Check firewall rules
sudo ufw status
sudo ufw allow 5432/tcp

# 4. Check listen_addresses in heliosdb.conf
# Should be: listen_addresses = '*'

Authentication Failed

Error: password authentication failed for user "helios"

Solutions:

# 1. Reset password
heliosdb user set-password --username=helios --password=newpassword

# 2. Check pg_hba.conf
# Should have: host all all 0.0.0.0/0 md5

# 3. Verify username
psql -h localhost -U helios -d myapp

Timeout Errors

Error: connection timeout

Solutions:

# Increase timeout
client = HeliosClient(
    host="localhost",
    connect_timeout=60  # Increase to 60 seconds
)

SSL Certificate Errors

Error: SSL error: certificate verify failed

Solutions:

# Option 1: Disable SSL verification (dev only!)
psql "postgresql://helios@localhost/myapp?sslmode=disable"

# Option 2: Trust self-signed certificate
psql "postgresql://helios@localhost/myapp?sslmode=require"

# Option 3: Verify with CA certificate
psql "postgresql://helios@localhost/myapp?sslmode=verify-full&sslrootcert=/path/to/ca.crt"

---

Connection String Format

PostgreSQL DSN Format

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

Examples:

# Basic
postgresql://helios@localhost/myapp

# With password
postgresql://helios:password@localhost:5432/myapp

# With SSL
postgresql://helios@localhost/myapp?sslmode=require

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

---

Last Updated: November 1, 2025 Version: v6.0 Phase 2 M1 Maintained by: HeliosDB Documentation Team

Next: Querying Data →