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. In the examples on this page, replace heliosdb/heliosdb with the image reference you receive.

Estimated Time: 30 minutes

Welcome to HeliosDB! This guide will help you install, configure, and run your first queries in under 30 minutes.

Prerequisites
Installation
Starting HeliosDB
Connecting to HeliosDB
Creating Your First Database
Running Your First Queries
Loading Sample Data
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:

Option 1: Docker (Recommended for Quick Start)

Fastest way to get started - no compilation required!

# Pull the latest HeliosDB image
docker pull heliosdb/heliosdb:latest

# Run HeliosDB container
docker run -d \
  --name heliosdb \
  -p 5432:5432 \
  -p 8080:8080 \
  -p 50051:50051 \
  -e HELIOSDB_PASSWORD=mysecretpassword \
  -v heliosdb_data:/var/lib/heliosdb \
  heliosdb/heliosdb:latest

# Verify it's running
docker logs heliosdb

# Expected output:
# HeliosDB v8.3.0 starting...
# Listening on PostgreSQL port 5432
# Listening on HTTP port 8080
# Listening on gRPC port 50051
# Database system is ready to accept connections

Ports:

5432: PostgreSQL wire protocol
8080: HTTP REST API
50051: gRPC API

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 (already running!).

Native Binary Deployment

Step 1: Initialize Data Directory

# Create data directory
sudo mkdir -p /var/lib/heliosdb
sudo chown $USER:$USER /var/lib/heliosdb

# Initialize database cluster
heliosdb init --data-dir=/var/lib/heliosdb

Output:

Initializing HeliosDB cluster...
✓ Creating directory structure
✓ Generating configuration files
✓ Creating system catalogs
✓ Initializing WAL directory
✓ Setting up authentication

Success! Database cluster initialized at /var/lib/heliosdb

Next steps:
  1. Edit /var/lib/heliosdb/heliosdb.conf (configuration)
  2. Edit /var/lib/heliosdb/pg_hba.conf (authentication)
  3. Start the server: heliosdb server start

Step 2: Configure Server (Optional)

Edit /var/lib/heliosdb/heliosdb.conf:

# Connection settings
listen_addresses = '*'          # Allow connections from any IP
port = 5432
max_connections = 1000

# Memory settings (adjust based on your RAM)
shared_buffers = '4GB'          # 25% of total RAM
work_mem = '256MB'
maintenance_work_mem = '1GB'

# Performance tuning
random_page_cost = 1.1          # For SSD storage
effective_cache_size = '12GB'   # 75% of total RAM

# Logging
log_destination = 'stderr'
logging_collector = on
log_directory = '/var/log/heliosdb'
log_filename = 'heliosdb-%Y-%m-%d.log'
log_statement = 'all'           # Log all SQL statements (dev only)

Step 3: Start the Server

# Start server in foreground (for testing)
heliosdb server start --data-dir=/var/lib/heliosdb

# Or start as background service (for production)
heliosdb server start --data-dir=/var/lib/heliosdb --daemon

# Check server status
heliosdb server status

# View logs
tail -f /var/log/heliosdb/heliosdb-$(date +%Y-%m-%d).log

Verify server is running:

# Check if port is listening
sudo netstat -tlnp | grep 5432
# Output: tcp 0 0 0.0.0.0:5432 0.0.0.0:* LISTEN 12345/heliosdb

Connecting to HeliosDB

Using psql (PostgreSQL Client)

Install psql (if not already installed):

# Ubuntu/Debian
sudo apt install postgresql-client

# macOS
brew install libpq

Connect to HeliosDB:

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

# Enter password: mysecretpassword (Docker) or your configured password

# You should see:
# psql (15.4, server HeliosDB 8.3.0)
# Type "help" for help.
#
# postgres=#

Using HeliosDB CLI

Native HeliosDB shell (better autocomplete and features):

heliosdb cli connect \
  --host=localhost \
  --port=5432 \
  --username=helios \
  --database=postgres

# Interactive shell:
# heliosdb> SELECT version();
#  version
# -----------
#  HeliosDB v6.0.0 on x86_64-pc-linux-gnu, compiled by rustc 1.75.0
# (1 row)

Using Python Client

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

pip install "psycopg[binary]"

Connect and query:

import psycopg

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

Option 3: Load Sample Database (TPC-H)

# Download and load TPC-H benchmark data
heliosdb load-sample --dataset=tpch --scale=1

# Available datasets:
# - tpch (TPC-H benchmark)
# - northwind (classic SQL database)
# - world (countries, cities, languages)
# - sakila (DVD rental database)

Next Steps

Congratulations! You’ve successfully installed HeliosDB and run your first queries. Here’s what to explore next:

1. Learn Advanced Querying

Query Guide - Comprehensive query examples
Data Types Reference - All supported data types

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

FAQ - Frequently Asked Questions
Support: support@heliosdb.com
Discord Community

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 Files

Server config: /var/lib/heliosdb/heliosdb.conf
Authentication: /var/lib/heliosdb/pg_hba.conf
Logs: /var/log/heliosdb/
Data directory: /var/lib/heliosdb/

Common Issues

Can’t connect to server?

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

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

Permission denied?

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

Out of memory?

-- Reduce memory settings in heliosdb.conf
shared_buffers = '1GB'
work_mem = '64MB'

Next: Connecting to HeliosDB →

Getting Started with HeliosDB

Getting Started with HeliosDB

Table of Contents

Prerequisites

System Requirements

Software Dependencies

Installation

Option 1: Docker (Recommended for Quick Start)

Option 2: Native Binary

Starting HeliosDB

Docker Deployment

Native Binary Deployment

Step 1: Initialize Data Directory

Step 2: Configure Server (Optional)

Step 3: Start the Server

Connecting to HeliosDB

Using psql (PostgreSQL Client)

Using HeliosDB CLI

Using Python Client

Creating Your First Database

Step 1: Create Database

Step 2: Create Schema

Running Your First Queries

Insert Data

Query Data

Update Data

Delete Data

Loading Sample Data

Option 1: Load from CSV

Option 2: Generate Random Data

Option 3: Load Sample Database (TPC-H)

Next Steps

1. Learn Advanced Querying

2. Explore Unique Features

3. Production Deployment

4. Development

5. Get Help

Quick Reference

Useful Commands

Configuration Files

Common Issues