---
title: "Connecting to HeliosDB"
---

# 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](#connection-protocols)
2. [Command-Line Clients](#command-line-clients)
3. [Programming Languages](#programming-languages)
4. [GUI Tools](#gui-tools)
5. [Connection Pooling](#connection-pooling)
6. [Security & Authentication](#security--authentication)
7. [Troubleshooting](#troubleshooting)

---

## Connection Protocols

HeliosDB supports multiple wire protocols for maximum compatibility:

| Protocol | Default port | Enabled by default | Use Case | Compatibility |
|----------|--------------|--------------------|----------|---------------|
| **PostgreSQL** | 5432 | Yes | Primary interface, broad tool and driver support | psql, pgAdmin, psycopg, pgx, JDBC, any PostgreSQL driver |
| **HTTP gateway** | 8443 | Yes | REST queries (`POST /api/v1/query`), Snowflake/Databricks/Pinecone-compatible APIs | curl, HeliosDB SDKs |
| **MySQL** | 3306 | No (`--enable-mysql`) | MySQL client compatibility | mysql CLI, MySQL Workbench |
| **SQL Server (TDS)** | 1433 | No (`--enable-sqlserver`) | SQL Server client compatibility | sqlcmd, TDS drivers |
| **Oracle (TNS)** | 1521 | No (`--enable-oracle`) | Oracle client compatibility | SQL*Plus, Oracle drivers |
| **Redis** | 6379 | No (`--enable-redis`) | Key-value access | redis-cli, Redis clients |
| **MongoDB** | 27017 | No (`--enable-mongodb`) | Document access | mongosh, MongoDB drivers |
| **Cassandra (CQL)** | 9042 | No (`--enable-cassandra`) | Wide-column access | cqlsh, CQL drivers |

Ports can be changed with `--postgres-port`, `--http-port` and the matching
`HELIOSDB_*_PORT` environment variables. HeliosDB Full has no gRPC client
API: application code connects over the PostgreSQL wire protocol (or one of
the protocols above).

---

## Command-Line Clients

HeliosDB Full has no separate command-line shell; use `psql`, the `mysql` client or
any client for the listener you connect to.

### 1. psql (PostgreSQL Client)

**Most widely used, excellent compatibility**

```bash
# 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**:
```sql
\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
```

### 2. mysql CLI

**For users familiar with MySQL**

```bash
# 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

HeliosDB Full speaks the PostgreSQL wire protocol, so use a standard PostgreSQL
driver such as [psycopg](https://www.psycopg.org/):

```bash
pip install "psycopg[binary]"

# Or the older psycopg2 driver
pip install psycopg2-binary
```

#### Synchronous Connection (psycopg 3)

```python
import psycopg

with psycopg.connect(
    host="localhost",
    port=5432,
    user="helios",
    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)

```python
import asyncio
import psycopg

async def main():
    async with await psycopg.AsyncConnection.connect(
        "postgresql://helios: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)

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

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

```bash
npm install pg

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

#### Node.js Connection

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

// Create client
const client = new Client({
  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

```typescript
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: 'helios',
  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

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

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

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

#### JDBC Connection

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

```yaml
# 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

HeliosDB Full speaks the PostgreSQL wire protocol, so any standard Go PostgreSQL driver works. The example below uses [pgx](https://github.com/jackc/pgx). (The Go REST client in [HeliosDB-SDKs/sdks/go](https://github.com/HeliosDatabase/HeliosDB-SDKs/tree/main/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

```bash
go get github.com/jackc/pgx/v5
```

#### Connection Example

```go
package main

import (
    "context"
    "fmt"
    "log"

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

func main() {
    ctx := context.Background()
    conn, err := pgx.Connect(ctx, "postgres://helios: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

HeliosDB Full speaks the PostgreSQL wire protocol, so use the standard
`tokio-postgres` driver.

#### Add Dependency

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

#### Connection Example

```rust
use tokio_postgres::{Error, NoTls};

#[tokio::main]
async fn main() -> Result<(), Error> {
    // Connect (the listeners do not terminate TLS; put a TLS proxy in front for remote clients)
    let (client, connection) = tokio_postgres::connect(
        "host=localhost port=5432 user=helios 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. HeliosDB Studio (Official GUI)

**Native desktop application** for HeliosDB

HeliosDB Studio is provided to licensed HeliosDB Full customers — contact [sales@heliosdb.com](mailto:sales@heliosdb.com).

**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:
   - Host: localhost
   - Port: 5432
   - Username: helios
   - 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

```python
# 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

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

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

:::caution[What the current release offers]
HeliosDB Full authenticates PostgreSQL clients with SCRAM-SHA-256; SQL GRANT/REVOKE enforcement, row-level security, encryption at rest with key rotation and cloud KMS, ABAC, SAML/OIDC single sign-on and LDAP are planned. HeliosDB Full listeners do not terminate TLS; put a TLS-terminating proxy in front, and native PostgreSQL TLS is planned for the next release. The TLS, client-certificate (mTLS), LDAP/Active Directory and OAuth2/OIDC sections below describe planned features.
:::

### Password Authentication

**Basic username/password** (default):

```bash
# 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**:

```bash
# 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**:
```python
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:

```bash
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`:
```toml
[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**:

```python
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**:
```bash
# 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**:
```bash
# 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**:
```python
# Increase timeout
client = HeliosClient(
    host="localhost",
    connect_timeout=60  # Increase to 60 seconds
)
```

### SSL Certificate Errors

**Error**: `SSL error: certificate verify failed`

**Solutions**:
```bash
# 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**:
```bash
# 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
```

---


**Next**: [Querying Data](https://www.heliosdb.com/docs/full/reference/user-guide/querying/) →