Skip to content
HeliosDB HeliosDB Nano

HeliosDB Nano Protocol Server - Quick Start Guide

HeliosDB Nano Protocol Server - Quick Start Guide

Overview

HeliosDB Nano now supports multi-protocol server mode, allowing clients to connect via Oracle TNS protocol (PostgreSQL coming soon).

Installation

Build from source:

Terminal window
cd /home/claude/HeliosDB Nano
cargo build --release

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

Starting the Server

Basic Start

Terminal window
heliosdb-nano start

This will:

  • Create data directory at ./heliosdb-data
  • Start Oracle TNS server on 127.0.0.1:1521
  • Display “NOT YET IMPLEMENTED” for PostgreSQL protocol

Custom Data Directory

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

Listen on All Interfaces

Terminal window
heliosdb-nano start --listen 0.0.0.0

Full Example

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


# You'll see output like:
# === HeliosDB Nano Multi-Protocol Server ===
# Data directory: "/var/lib/heliosdb"
# Database initialized successfully
# Protocol Configuration:
#   - Oracle TNS: 0.0.0.0:1521 (ENABLED)
#   - PostgreSQL: 0.0.0.0:5432 (NOT YET IMPLEMENTED)
# ...
# Starting Oracle TNS server on 0.0.0.0:1521
# Oracle TNS server listening on 0.0.0.0:1521

Connecting to the Server

Using Oracle SQL*Plus

Terminal window
sqlplus username/password@//localhost:1521/HELIOSDB

Example session:

SQL> CREATE TABLE users (id INT, name TEXT);
Table created.


SQL> INSERT INTO users VALUES (1, 'Alice');
1 row inserted.


SQL> SELECT * FROM users;
        ID NAME
---------- ----------
         1 Alice

Using Oracle SQLcl

Terminal window
sql username/password@//localhost:1521/HELIOSDB

Using Python (cx_Oracle)

import cx_Oracle


# Connect to HeliosDB Nano
conn = cx_Oracle.connect(
    "username",
    "password",
    "localhost:1521/HELIOSDB"
)


# Create cursor
cursor = conn.cursor()


# Execute SQL
cursor.execute("CREATE TABLE users (id INT, name TEXT)")
cursor.execute("INSERT INTO users VALUES (1, 'Alice')")


# Query data
cursor.execute("SELECT * FROM users")
for row in cursor:
    print(row)


# Close connection
cursor.close()
conn.close()

Using Java (JDBC)

import java.sql.*;


public class HeliosDBExample {
    public static void main(String[] args) throws SQLException {
        // Connect to HeliosDB Nano
        String url = "jdbc:oracle:thin:@localhost:1521:HELIOSDB";
        Connection conn = DriverManager.getConnection(
            url, "username", "password"
        );


        // 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 (Oracle Dialect)

HeliosDB Nano translates Oracle SQL to its internal format:

Tables

-- Create table
CREATE TABLE users (
    id NUMBER PRIMARY KEY,
    name VARCHAR2(100),
    email VARCHAR2(255),
    created_date DATE
);


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


-- 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;

Oracle-Specific Functions (Translated)

-- SYSDATE → CURRENT_TIMESTAMP
SELECT SYSDATE FROM DUAL;


-- NVL() → COALESCE()
SELECT NVL(column, 'default') FROM table;


-- DECODE() → CASE WHEN
SELECT DECODE(status, 'A', 'Active', 'I', 'Inactive') FROM users;


-- Dual table emulation
SELECT 1 + 1 FROM DUAL;

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)
Oracle server shutting down
Waiting for protocol servers to shut down...
All protocol servers shut down successfully
Server shutdown complete

Other Modes

REPL Mode (Interactive)

Terminal window
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

Terminal window
heliosdb-nano init /path/to/database

Troubleshooting

Port Already in Use

Error: “Failed to bind to 127.0.0.1:1521”

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

Terminal window
# Find what's using the port
lsof -i :1521


# Use a different port (requires Oracle server modification)
# Currently port is hardcoded to 1521

Connection Refused

Error: Client cannot connect

Solution:

  1. Verify server is running: ps aux | grep heliosdb-nano
  2. Check if firewall is blocking port 1521
  3. Try connecting from localhost first
  4. Check server logs for errors

PostgreSQL Client Won’t Connect

Error: psql or other PostgreSQL clients fail to connect

Reason: PostgreSQL wire protocol is not yet implemented. Currently only Oracle TNS protocol works.

Solution: Use Oracle client tools or wait for PostgreSQL protocol implementation.

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

Terminal window
# 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

  1. Read full documentation: /home/claude/HeliosDB Nano/docs/PROTOCOL_INTEGRATION_COMPLETE.md
  2. Review Oracle protocol details: /home/claude/HeliosDB Nano/src/protocols/oracle/
  3. Check adapter layer: /home/claude/HeliosDB Nano/src/protocols/adapters/
  4. Run tests: cargo test --test protocol_integration_test

Support

For issues or questions:

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

Limitations (Current Version)

  1. PostgreSQL Protocol: Not yet implemented (shows “NOT YET IMPLEMENTED”)
  2. Oracle Features: Basic SQL only (no PL/SQL, packages, procedures)
  3. Authentication: Basic auth only (no Kerberos, SSL)
  4. Replication: Not yet available
  5. Clustering: Single-node only

These features will be added in future releases.