HeliosDB Nano Protocol Server - Quick Start Guide

Overview

HeliosDB Nano server mode exposes the PostgreSQL wire protocol by default, with optional MySQL protocol support when enabled.

Installation

Build from source:

cd ~/HeliosDB Nano
cargo build --release

The binary will be at target/release/heliosdb-nano.

Starting the Server

Basic Start

heliosdb-nano start

This will:

Create data directory at ./heliosdb-data
Start a PostgreSQL-compatible server on 127.0.0.1:5432
Start the HTTP health endpoint unless disabled with --http-port 0

Custom Data Directory

heliosdb-nano start --data-dir /var/lib/heliosdb

Listen on All Interfaces

heliosdb-nano start --listen 0.0.0.0

Full Example

# Start server with custom settings
heliosdb-nano start \
  --data-dir /var/lib/heliosdb \
  --listen 0.0.0.0 \
  --port 5432

# The startup banner prints PostgreSQL connection strings for psql,
# Python, Node.js, and JDBC clients.

Connecting to the Server

Using psql

psql -h localhost -p 5432 -d heliosdb

Example session:

heliosdb=> CREATE TABLE users (id INT, name TEXT);
CREATE TABLE

heliosdb=> INSERT INTO users VALUES (1, 'Alice');
INSERT 0 1

heliosdb=> SELECT * FROM users;
 id | name
----+-------
  1 | Alice

Using Python

import psycopg

with psycopg.connect("host=localhost port=5432 dbname=heliosdb") as conn:
    with conn.cursor() as cur:
        cur.execute("CREATE TABLE users (id INT, name TEXT)")
        cur.execute("INSERT INTO users VALUES (1, 'Alice')")
        cur.execute("SELECT * FROM users")
        print(cur.fetchall())

Using Java (JDBC)

import java.sql.*;

public class HeliosDBExample {
    public static void main(String[] args) throws SQLException {
        // Connect to HeliosDB Nano
        String url = "jdbc:postgresql://localhost:5432/heliosdb";
        Connection conn = DriverManager.getConnection(url, "postgres", "");

        // Execute SQL
        Statement stmt = conn.createStatement();
        stmt.execute("CREATE TABLE users (id INT, name TEXT)");
        stmt.execute("INSERT INTO users VALUES (1, 'Alice')");

        // Query data
        ResultSet rs = stmt.executeQuery("SELECT * FROM users");
        while (rs.next()) {
            System.out.println(
                "ID: " + rs.getInt("id") +
                ", Name: " + rs.getString("name")
            );
        }

        // Close
        rs.close();
        stmt.close();
        conn.close();
    }
}

Supported SQL

Use PostgreSQL-style SQL from clients:

Tables

-- Create table
CREATE TABLE users (
    id INT PRIMARY KEY,
    name VARCHAR(100),
    email VARCHAR(255),
    created_at TIMESTAMP
);

-- Insert data
INSERT INTO users VALUES (1, 'Alice', 'alice@example.com', CURRENT_TIMESTAMP);

-- Query data
SELECT * FROM users;
SELECT * FROM users WHERE id = 1;

-- Update data
UPDATE users SET email = 'newemail@example.com' WHERE id = 1;

-- Delete data
DELETE FROM users WHERE id = 1;

-- Drop table
DROP TABLE users;

Vector Search (HeliosDB Extension)

-- Create table with vector column
CREATE TABLE embeddings (
    id INT,
    content TEXT,
    embedding VECTOR(768)
);

-- Insert vector data
INSERT INTO embeddings VALUES (
    1,
    'Hello world',
    '[0.1, 0.2, 0.3, ...]'::VECTOR
);

-- Vector similarity search
SELECT * FROM embeddings
ORDER BY embedding <-> '[0.1, 0.2, 0.3, ...]'::VECTOR
LIMIT 10;

Stopping the Server

Press Ctrl+C to gracefully shut down:

^C
Received shutdown signal (Ctrl+C)
Server shutting down
Protocol listeners stopped
Server shutdown complete

Other Modes

REPL Mode (Interactive)

heliosdb-nano repl

Interactive SQL shell:

HeliosDB Nano v2.0.0 - Interactive Shell
Type 'help' for help, 'exit' to quit

helios> CREATE TABLE users (id INT, name TEXT);
OK (1 row affected)

helios> INSERT INTO users VALUES (1, 'Alice');
OK (1 row inserted)

helios> SELECT * FROM users;
+----+-------+
| id | name  |
+----+-------+
| 1  | Alice |
+----+-------+
1 row

helios> exit
Goodbye!

Initialize New Database

heliosdb-nano init /path/to/database

Troubleshooting

Port Already in Use

Error: “Failed to bind to 127.0.0.1:5432”

Solution: Another process is using port 5432. Either stop that process or use a different port:

# Find what's using the port
lsof -i :5432

# Use a different port
heliosdb-nano start --port 15432

Connection Refused

Error: Client cannot connect

Solution:

Verify server is running: ps aux | grep heliosdb-nano
Check if firewall is blocking the configured server port
Try connecting from localhost first
Check server logs for errors

PostgreSQL Client Won’t Connect

Error: psql or other PostgreSQL clients fail to connect

Reason: The server may not be running, may be bound to a different address, or may require authentication options that the client did not provide.

Solution: Check the startup banner for the exact host and port, then retry with the matching psql -h <host> -p <port> settings.

File Locations

After starting the server, you’ll find:

./heliosdb-data/              # Data directory
├── CURRENT                   # RocksDB current version
├── IDENTITY                  # Database identity
├── LOCK                      # Lock file
├── LOG                       # RocksDB log
├── MANIFEST-*               # RocksDB manifest
├── OPTIONS-*                # RocksDB options
└── *.sst                    # Data files (SST tables)

Environment Variables

# Set log level
export RUST_LOG=info
export RUST_LOG=debug  # More verbose
export RUST_LOG=trace  # Most verbose

# Start server with logging
RUST_LOG=debug heliosdb-nano start

Next Steps

Review PostgreSQL protocol tests in tests/protocol_tests.rs
Check adapter layer source in src/protocols/adapters/
Run protocol checks with cargo test protocol

Support

For issues or questions:

Check documentation in ~/HeliosDB Nano/docs/
Review test files for usage examples
Examine source code in ~/HeliosDB Nano/src/

Operating Notes

Configure authentication with --auth and --password when exposing the server outside local development.
Use --tls-cert and --tls-key when clients require TLS.
Use --mysql only when the MySQL compatibility listener is needed.
Use --http-port 0 to disable the HTTP health endpoint.