Skip to content
HeliosDB HeliosDB Full

Getting Started with HeliosDB

Container images: HeliosDB Full images are not published on Docker Hub or any other public registry. Images and Helm charts are provided through private registry access during onboarding: contact sales@heliosdb.com. The examples on this page use heliosdb-full:<tag>, an image built locally from the licensed source distribution (docker build -t heliosdb-full:<tag> .); replace it with the image reference you receive if you use the private registry.

Estimated Time: 30 minutes

This guide helps you install, configure and run your first queries in under 30 minutes.

Table of Contents

  1. Prerequisites
  2. Installation
  3. Starting HeliosDB
  4. Connecting to HeliosDB
  5. Creating Your First Database
  6. Running Your First Queries
  7. Loading Sample Data
  8. Next Steps

Prerequisites

System Requirements

Minimum (for development/testing):

  • CPU: 2 cores
  • RAM: 4 GB
  • Disk: 10 GB available space
  • OS: Linux, macOS, or Windows

Recommended (for production):

  • CPU: 8+ cores
  • RAM: 32+ GB
  • Disk: 100+ GB SSD (NVMe preferred)
  • Network: 10 Gbps
  • OS: Ubuntu 22.04 LTS or RHEL 9

Software Dependencies

  • Rust: 1.75+ (if building from source)
  • Docker: 24.0+ (for containerized deployment)
  • PostgreSQL client: 14+ (for psql CLI)

Installation

Choose one of the following installation methods:

Quickest way to start: no compilation required.

Terminal window
# Build the HeliosDB Full image from the licensed source distribution
docker build -t heliosdb-full:latest .


# Run HeliosDB container
docker run -d --name heliosdb \
  -e HELIOSDB_ALLOW_EXTERNAL=1 \
  -p 127.0.0.1:5432:5432 \
  -p 127.0.0.1:8443:8443 \
  -v heliosdb_data:/var/lib/heliosdb/data \
  heliosdb-full:latest


# Verify it's running
docker logs heliosdb 2>&1 | grep -E "listening|Server ready"


# Expected output:
# PostgreSQL protocol listening on 0.0.0.0:5432
# HTTP Gateway listening on 0.0.0.0:8443
# Server ready - accepting connections

The image binds all interfaces inside the container, so it needs HELIOSDB_ALLOW_EXTERNAL=1 to start; the -p options above publish the ports on the host’s loopback address only. For credentials and the MySQL and Oracle listeners, follow the Quick Start.

Ports:

  • 5432: PostgreSQL wire protocol
  • 8443: HTTP gateway (plain HTTP; POST /api/v1/query)

Option 2: Native Binary

HeliosDB Full is distributed to licensed customers. Native binaries, container images and source access are provided during onboarding — contact sales@heliosdb.com for access.

Starting HeliosDB

Docker Deployment

If you installed via Docker, skip this section (the server is already running).

Native Binary Deployment

The server binary is heliosdb-full. It has no init or server subcommands: it creates the data directory on first start and runs in the foreground until you stop it (run it under systemd or another supervisor for production).

Terminal window
# Start the server (PostgreSQL on 5432 and the HTTP gateway on 8443, bound to 127.0.0.1)
heliosdb-full --data-dir /var/lib/heliosdb/data


# More listeners
heliosdb-full --data-dir /var/lib/heliosdb/data --enable-mysql --enable-oracle


# Remote clients: bind a private address and opt in explicitly
heliosdb-full --data-dir /var/lib/heliosdb/data --bind-addr 10.0.0.12 --allow-external

Settings come from command-line flags and HELIOSDB_* environment variables; a TOML file can be passed with --config (or HELIOSDB_CONFIG). See the Server Configuration Reference.

Verify server is running:

Terminal window
curl -s http://127.0.0.1:8443/health
# {"status":"healthy","version":"..."}


ss -tlnp | grep 5432

Connecting to HeliosDB

Using psql (PostgreSQL Client)

Install psql (if not already installed):

Terminal window
# Ubuntu/Debian
sudo apt install postgresql-client


# macOS
brew install libpq

Connect to HeliosDB:

Terminal window
# Using default settings
psql -h localhost -p 5432 -U postgres -d postgres


# Enter the superuser password (see the Quick Start credentials table)


# You should see:
# psql (15.4, server <version>)
# Type "help" for help.
#
# postgres=#

Using Python Client

Install a PostgreSQL driver (HeliosDB Full speaks the PostgreSQL wire protocol):

Terminal window
pip install "psycopg[binary]"

Connect and query:

import os
import psycopg


with psycopg.connect(
    host="localhost",
    port=5432,
    user="postgres",
    password=os.environ["PGPASSWORD"],  # the superuser password
    dbname="postgres",
) as conn:
    print(conn.execute("SELECT version()").fetchone())

See CONNECTING.md for more connection methods (Java, JavaScript, Go, etc.).

Creating Your First Database

Step 1: Create Database

-- Create a new database
CREATE DATABASE myapp;


-- List all databases
\l


-- Connect to new database
\c myapp

Step 2: Create Schema

-- Create users table
CREATE TABLE users (
    id SERIAL PRIMARY KEY,
    username VARCHAR(50) UNIQUE NOT NULL,
    email VARCHAR(255) UNIQUE NOT NULL,
    created_at TIMESTAMP DEFAULT NOW(),
    profile JSONB
);


-- Create indexes
CREATE INDEX idx_users_email ON users(email);
CREATE INDEX idx_users_created_at ON users(created_at);


-- Create posts table
CREATE TABLE posts (
    id SERIAL PRIMARY KEY,
    user_id INTEGER REFERENCES users(id) ON DELETE CASCADE,
    title VARCHAR(255) NOT NULL,
    content TEXT,
    published_at TIMESTAMP,
    tags TEXT[],
    metadata JSONB
);


-- Create index on foreign key
CREATE INDEX idx_posts_user_id ON posts(user_id);

Running Your First Queries

Insert Data

-- Insert users
INSERT INTO users (username, email, profile) VALUES
('alice', 'alice@example.com', '{"role": "admin", "verified": true}'),
('bob', 'bob@example.com', '{"role": "user", "verified": false}'),
('charlie', 'charlie@example.com', '{"role": "moderator", "verified": true}');


-- Insert posts
INSERT INTO posts (user_id, title, content, published_at, tags) VALUES
(1, 'Getting Started with HeliosDB', 'This is my first post...', NOW(), ARRAY['heliosdb', 'tutorial']),
(1, 'Advanced Features', 'Let me show you...', NOW(), ARRAY['heliosdb', 'advanced']),
(2, 'Hello World', 'My introduction...', NOW(), ARRAY['intro']);

Query Data

-- Simple SELECT
SELECT * FROM users;


-- Filter with WHERE
SELECT username, email
FROM users
WHERE profile->>'role' = 'admin';


-- JOIN tables
SELECT u.username, p.title, p.published_at
FROM users u
JOIN posts p ON u.id = p.user_id
WHERE p.published_at > NOW() - INTERVAL '7 days'
ORDER BY p.published_at DESC;


-- Aggregate data
SELECT u.username, COUNT(p.id) AS post_count
FROM users u
LEFT JOIN posts p ON u.id = p.user_id
GROUP BY u.id, u.username
ORDER BY post_count DESC;

Update Data

-- Update single row
UPDATE users
SET profile = profile || '{"verified": true}'
WHERE username = 'bob';


-- Update with JOIN
UPDATE posts
SET metadata = '{"featured": true}'
WHERE user_id IN (
    SELECT id FROM users WHERE profile->>'role' = 'admin'
);

Delete Data

-- Delete with condition
DELETE FROM posts WHERE published_at IS NULL;


-- Cascade delete (posts will be auto-deleted due to FK constraint)
DELETE FROM users WHERE username = 'charlie';

Loading Sample Data

Option 1: Load from CSV

-- Create table
CREATE TABLE sales (
    id SERIAL PRIMARY KEY,
    product VARCHAR(100),
    quantity INTEGER,
    price DECIMAL(10,2),
    sale_date DATE
);


-- Load from CSV
COPY sales (product, quantity, price, sale_date)
FROM '/path/to/sales.csv'
DELIMITER ','
CSV HEADER;


-- Verify
SELECT COUNT(*) FROM sales;

Option 2: Generate Random Data

-- Install random data generator extension
CREATE EXTENSION IF NOT EXISTS helios_random;


-- Generate 1 million random users
INSERT INTO users (username, email, profile)
SELECT
    'user_' || generate_series AS username,
    'user' || generate_series || '@example.com' AS email,
    json_build_object(
        'role', (ARRAY['user', 'admin', 'moderator'])[floor(random() * 3 + 1)],
        'verified', random() > 0.5
    )::jsonb AS profile
FROM generate_series(1, 1000000);


-- Verify
SELECT COUNT(*) FROM users;
-- Output: 1000000

Next Steps

With HeliosDB installed and your first queries run, these are the next topics:

1. Learn Advanced Querying

2. Explore Unique Features

  • Vector Search: Vector Search Guide
  • Natural Language Queries: NL2SQL Guide
  • Time-Series: Time-Series Guide
  • Graph Queries: Graph Query Guide

3. Production Deployment

4. Development

5. Get Help

Quick Reference

Useful Commands

-- List databases
\l


-- List tables
\dt


-- Describe table
\d users


-- List indexes
\di


-- Show current database
SELECT current_database();


-- Show server version
SELECT version();


-- Show active connections
SELECT * FROM pg_stat_activity;


-- Show database size
SELECT pg_size_pretty(pg_database_size('myapp'));


-- Show table size
SELECT pg_size_pretty(pg_total_relation_size('users'));

Configuration and Files

  • Settings: command-line flags and HELIOSDB_* environment variables; an optional TOML file via --config
  • Logs: the server’s standard output (docker logs heliosdb for the container)
  • Data directory: --data-dir (/var/lib/heliosdb/data in the container image)

Common Issues

Can’t connect to server?

Terminal window
# Check if the server is running
curl -s http://127.0.0.1:8443/health
docker ps --filter name=heliosdb


# Check if port is listening
ss -tlnp | grep 5432

The server binds 127.0.0.1 by default; remote clients need --bind-addr and --allow-external.

Permission denied?

Terminal window
# Fix data directory permissions
sudo chown -R $USER:$USER /var/lib/heliosdb

Next: Connecting to HeliosDB →