Getting Started with HeliosDB

Getting Started with HeliosDB

Last Updated: November 1, 2025 Version: v6.0 Phase 2 M1 Estimated Time: 30 minutes

Welcome to HeliosDB! This guide will help 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:

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 v6.0.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: Pre-Built Binary (Linux/macOS)

For production deployments - native performance!

# Download the latest release
curl -LO https://github.com/heliosdb/heliosdb/releases/latest/download/heliosdb-$(uname -s)-$(uname -m)

# Make it executable
chmod +x heliosdb-$(uname -s)-$(uname -m)

# Move to system path
sudo mv heliosdb-$(uname -s)-$(uname -m) /usr/local/bin/heliosdb

# Verify installation
heliosdb --version
# Output: HeliosDB v6.0.0 (build 2025-11-01)

Option 3: Build from Source (For Developers)

For contributors and advanced users - full control!

# Clone the repository
git clone https://github.com/heliosdb/heliosdb.git
cd heliosdb

# Build release binary (optimized)
cargo build --release

# Binary location: ./target/release/heliosdb
./target/release/heliosdb --version

# (Optional) Install system-wide
sudo cp ./target/release/heliosdb /usr/local/bin/

# (Optional) Run tests
cargo test --release

Build time: ~10-15 minutes on 8-core machine

---

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 6.0.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 client library:

pip install heliosdb-py

Connect and query:

from heliosdb import HeliosClient

# Create client
client = HeliosClient(
    host="localhost",
    port=5432,
    user="helios",
    password="mysecretpassword",
    database="postgres"
)

# Connect
client.connect()

# Run query
result = client.execute("SELECT version()")
print(result.rows[0])

# Output: ('HeliosDB v6.0.0 on x86_64-pc-linux-gnu',)

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
• SQL Reference - Complete SQL syntax

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

• Deployment Guide - Production best practices
• Performance Tuning - Optimization tips
• Monitoring - Metrics and dashboards
• Backup & Recovery - Data protection

4. Development

• Python Client Guide
• JavaScript Client Guide
• Java JDBC Driver
• REST API Reference

5. Get Help

• FAQ - Frequently Asked Questions
• Troubleshooting - Common issues
• GitHub Issues
• 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'

---

Last Updated: November 1, 2025 Version: v6.0 Phase 2 M1 Maintained by: HeliosDB Documentation Team

Next: Connecting to HeliosDB →