HeliosDB Nano v3.3.0 Quick Start Guide

Installation

# Build from source
git clone https://github.com/dimensigon/HDB-HeliosDB-Nano
cd HeliosDB Nano
cargo build --release

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

Starting HeliosDB Nano

Option 1: Interactive REPL (Single-User Development)

# In-memory database (data lost on exit)
heliosdb-nano repl --memory

# Persistent database
heliosdb-nano repl -d ./mydb

Option 2: Server Mode (Multi-User/Production)

# Start server (foreground)
heliosdb-nano start -d ./mydb --port 5432

# Start as daemon (background)
heliosdb-nano start --daemon -d ./mydb --port 5432

# Check status / stop daemon
heliosdb-nano status
heliosdb-nano stop

Connecting to Server Mode

Once the server is running, connect using any PostgreSQL client:

# Using psql
psql -h 127.0.0.1 -p 5432

# Using connection string
psql postgresql://127.0.0.1:5432/heliosdb

First Steps in REPL

-- Get help
heliosdb> \h

-- Create a table
heliosdb> CREATE TABLE users (
       ->   id SERIAL PRIMARY KEY,
       ->   name TEXT NOT NULL,
       ->   email TEXT UNIQUE
       -> );
Query OK

-- Insert data
heliosdb> INSERT INTO users (name, email)
       -> VALUES ('Alice', 'alice@example.com'),
       ->        ('Bob', 'bob@example.com');
Query OK, 2 rows affected

-- Query data
heliosdb> SELECT * FROM users;
 id | name  | email
----+-------+------------------
  1 | Alice | alice@example.com
  2 | Bob   | bob@example.com
(2 rows)

-- List tables
heliosdb> \d
Tables:
  users

-- Describe table
heliosdb> \d users
Table: users
──────────────────────────────────────────────────
Column     Type      Nullable   Primary Key
──────────────────────────────────────────────────
id         Integer   NO         YES
name       Text      NO
email      Text      YES

Essential REPL Commands

Basic Commands

\h              Show help
\d              List all tables
\d <table>      Describe table schema
\dt             List tables with details
\timing         Toggle query timing
\q              Quit

v2.0 Features

\branches       List database branches
\snapshots      List time-travel snapshots
\dmv            List materialized views
\compression    Show compression statistics

v2.1 Features

\set            Show all settings
\config         Show configuration
\stats          Show database statistics
\optimize <t>   Optimization recommendations

Essential SQL Commands

Settings Management

-- Show current settings
SHOW ALL;
SHOW optimizer;

-- Set timeouts
SET statement_timeout = 30000;  -- 30 seconds

-- Set memory
SET work_mem = 16384;  -- 16MB

-- Enable optimizer
SET optimizer = on;

Time-Travel Queries

-- Enable time-travel
SET time_travel_enabled = on;

-- Query historical data
SELECT * FROM orders
  AS OF TIMESTAMP '2025-11-23 10:00:00'
  WHERE customer_id = 123;

Database Branching

-- Create a branch
CREATE DATABASE BRANCH dev FROM main AS OF NOW;

-- Work on branch
USE BRANCH dev;

-- Merge back
MERGE DATABASE BRANCH dev INTO main;

Materialized Views

-- Create materialized view
CREATE MATERIALIZED VIEW customer_stats AS
  SELECT
    customer_id,
    COUNT(*) as order_count,
    SUM(amount) as total_spent
  FROM orders
  GROUP BY customer_id
  WITH (auto_refresh = true, max_cpu_percent = 15);

-- Refresh manually
REFRESH MATERIALIZED VIEW customer_stats;

-- Query materialized view
SELECT * FROM customer_stats;

Vector Search

-- Create table with vector column
CREATE TABLE documents (
  id SERIAL PRIMARY KEY,
  content TEXT,
  embedding VECTOR(384)
);

-- Create vector index
CREATE INDEX ON documents USING hnsw(embedding);

-- Similarity search
SELECT id, content
FROM documents
ORDER BY embedding <-> '[0.1, 0.2, ...]'::vector
LIMIT 10;

Compression

-- Set compression for table
ALTER TABLE large_table SET COMPRESSION zstd;

-- Check compression stats
\compression large_table

Configuration File

Basic Configuration (config.toml)

# Storage
[storage]
path = "./heliosdb-data"
wal_enabled = true
time_travel_enabled = true
cache_size = 536870912  # 512MB

# Server
[server]
listen_addr = "127.0.0.1"
port = 5432
max_connections = 100

# Performance
[performance]
worker_threads = 0  # Auto-detect
simd_enabled = true
parallel_query = true

# Optimizer
[optimizer]
enabled = true
random_page_cost = 4.0  # 1.1 for SSD

# Compression
[compression]
default_type = "Zstd"
level = 3

Start with Configuration

# Copy example
cp config.example.toml config.toml

# Edit configuration
nano config.toml

# Start with config
heliosdb-nano start --config config.toml

Common Use Cases

Analytics Workload

-- Configure for analytics
SET work_mem = 131072;          -- 128MB
SET shared_buffers = 1048576;   -- 1GB
SET optimizer = on;
SET enable_seqscan = on;

-- Run analytics query
SELECT
  DATE_TRUNC('day', created_at) as date,
  COUNT(*) as order_count,
  SUM(amount) as total_amount
FROM orders
GROUP BY date
ORDER BY date DESC;

OLTP Workload

-- Configure for OLTP
SET work_mem = 4096;            -- 4MB
SET statement_timeout = 5000;   -- 5 seconds
SET enable_indexscan = on;

-- Transactional queries
BEGIN;
INSERT INTO orders (customer_id, amount) VALUES (123, 99.99);
UPDATE customers SET total_spent = total_spent + 99.99 WHERE id = 123;
COMMIT;

Data Warehouse

-- Create materialized views for aggregations
CREATE MATERIALIZED VIEW daily_sales AS
  SELECT
    DATE_TRUNC('day', created_at) as date,
    product_id,
    COUNT(*) as sales_count,
    SUM(amount) as revenue
  FROM orders
  GROUP BY date, product_id
  WITH (auto_refresh = true);

-- Query aggregated data
SELECT * FROM daily_sales
WHERE date >= CURRENT_DATE - INTERVAL '30 days';

Vector Similarity Search

-- Configure vector indexes
SET vector_index_type = 'hnsw';
SET hnsw_ef_construction = 200;

-- Create embeddings table
CREATE TABLE embeddings (
  id SERIAL PRIMARY KEY,
  document_id INT,
  embedding VECTOR(384)
);

-- Create index
CREATE INDEX ON embeddings USING hnsw(embedding);

-- Similarity search
SELECT document_id
FROM embeddings
ORDER BY embedding <-> $1::vector
LIMIT 10;

Performance Tips

Enable timing to identify slow queries:
```
\timing
```

Use EXPLAIN to understand query plans:

EXPLAIN SELECT * FROM large_table WHERE id > 1000;

Set appropriate timeouts:

SET statement_timeout = 30000;  -- 30 seconds

Tune memory for workload:

-- Analytics: more memory
SET work_mem = 131072;  -- 128MB

-- OLTP: less memory, more concurrency
SET work_mem = 4096;    -- 4MB

Use compression for large tables:
```
ALTER TABLE logs SET COMPRESSION zstd;
```

Create materialized views for expensive queries:

CREATE MATERIALIZED VIEW expensive_query AS
  SELECT ... complex query ...
  WITH (auto_refresh = true);

Troubleshooting

Query too slow

-- Check query plan
EXPLAIN SELECT * FROM table WHERE condition;

-- Get index recommendations
\indexes table_name

-- Increase work memory
SET work_mem = 16384;

-- Enable timing
\timing

Out of memory

-- Reduce work_mem
SET work_mem = 2048;

-- Disable parallel execution
SET parallel_query = off;

-- Check current settings
SHOW work_mem;
SHOW shared_buffers;

Connection issues

# Check server status
\server status

# Check configuration
\config

# Restart server
heliosdb-nano start --config config.toml

Next Steps

Read the documentation:
Explore features:
- Time-travel queries
- Database branching
- Materialized views
- Vector search
Optimize performance:
- Use EXPLAIN for query plans
- Create appropriate indexes
- Tune memory settings
- Enable compression
Set up production:
- Configure TLS/SSL
- Enable authentication
- Set up audit logging
- Configure backups

Resources

Documentation: /docs/
Examples: /examples/
Configuration: config.example.toml
Deployment Modes: docs/guides/MODE_SELECTION_GUIDE.md
GitHub: https://github.com/dimensigon/HDB-HeliosDB-Nano
Issues: https://github.com/dimensigon/HDB-HeliosDB-Nano/issues

Getting Help

-- In REPL
\h              General help
\h <command>    Command-specific help

-- Show settings
SHOW ALL;

-- Show configuration
\config

-- Show statistics
\stats

Quick Reference Card

Task	REPL	SQL	Config
List tables	`\d`	`SELECT * FROM pg_tables`	-
Set timeout	`\set statement_timeout 30000`	`SET statement_timeout = 30000;`	`[storage] query_timeout_ms = 30000`
Enable optimizer	`\set optimizer on`	`SET optimizer = on;`	`[optimizer] enabled = true`
Time-travel	`\snapshots`	`AS OF TIMESTAMP '...'`	`[storage] time_travel_enabled = true`
Compression	`\compression`	`ALTER TABLE ... SET COMPRESSION`	`[compression] default_type = "Zstd"`
View config	`\config`	`SHOW ALL;`	-
Get help	`\h`	-	-

Welcome to HeliosDB Nano! Start exploring with \h in the REPL.