---
title: "Getting Started with HeliosDB"
---

# 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](mailto: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](#prerequisites)
2. [Installation](#installation)
3. [Starting HeliosDB](#starting-heliosdb)
4. [Connecting to HeliosDB](#connecting-to-heliosdb)
5. [Creating Your First Database](#creating-your-first-database)
6. [Running Your First Queries](#running-your-first-queries)
7. [Loading Sample Data](#loading-sample-data)
8. [Next Steps](#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)

**Quickest way to start**: no compilation required.

```bash
# 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](/docs/full/quickstart/).

**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](mailto: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).

```bash
# 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](/docs/full/reference/configuration/).

**Verify server is running**:
```bash
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):
```bash
# Ubuntu/Debian
sudo apt install postgresql-client

# macOS
brew install libpq
```

**Connect to HeliosDB**:
```bash
# 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):
```bash
pip install "psycopg[binary]"
```

**Connect and query**:
```python
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](https://www.heliosdb.com/docs/full/guides/user/connecting/) for more connection methods (Java, JavaScript, Go, etc.).

---

## Creating Your First Database

### Step 1: Create Database

```sql
-- Create a new database
CREATE DATABASE myapp;

-- List all databases
\l

-- Connect to new database
\c myapp
```

### Step 2: Create Schema

```sql
-- 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

```sql
-- 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

```sql
-- 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

```sql
-- 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

```sql
-- 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

```sql
-- 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

```sql
-- 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

- [Query Guide](https://www.heliosdb.com/docs/full/guides/user/querying/) - Comprehensive query examples
- [Data Types Reference](https://www.heliosdb.com/docs/full/guides/user/data_types/) - 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](https://www.heliosdb.com/docs/full/guides/user/faq/) - Frequently Asked Questions
- Support: [support@heliosdb.com](mailto:support@heliosdb.com)
- [Discord Community](https://discord.gg/yTykuUrFXc)

---

## Quick Reference

### Useful Commands

```sql
-- 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?**
```bash
# 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?**
```bash
# Fix data directory permissions
sudo chown -R $USER:$USER /var/lib/heliosdb
```

---


**Next**: [Connecting to HeliosDB](https://www.heliosdb.com/docs/full/guides/user/connecting/) →