Getting Started with HeliosDB Nano

Getting Started with HeliosDB Nano

Welcome to HeliosDB Nano! This guide will help you get up and running in 5 minutes.

Table of Contents

• Installation
• Quick Start
• Usage Modes
• Common Use Cases
• Next Steps

Installation

Prerequisites

• Rust 1.75+ (for building from source)
• Operating System: Linux, macOS, or Windows

Option 1: Cargo (Recommended)

# Install directly from crates.io (coming soon)
cargo install heliosdb-nano

# Or build from source
git clone https://github.com/heliosdb/heliosdb
cd heliosdb/heliosdb-nano
cargo build --release

Option 2: Docker

docker pull heliosdb/lite:latest
docker run -it --rm heliosdb/lite:latest

Option 3: Homebrew (macOS/Linux)

# Coming soon
brew install heliosdb-nano

Quick Start

1. Interactive REPL (Fastest Way to Try)

# Start in-memory database (no persistence)
heliosdb-nano repl --memory

# Or with persistent storage
heliosdb-nano repl -d ./mydb

Example session:

heliosdb> CREATE TABLE users (
  id SERIAL PRIMARY KEY,
  name TEXT NOT NULL,
  email TEXT UNIQUE,
  created_at TIMESTAMP DEFAULT NOW()
);
Query OK (0.002s)

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

heliosdb> SELECT * FROM users;
+----+-------+-------------------+-------------------------+
| id | name  | email             | created_at              |
+----+-------+-------------------+-------------------------+
| 1  | Alice | alice@example.com | 2025-11-15 13:00:00.000 |
| 2  | Bob   | bob@example.com   | 2025-11-15 13:00:00.001 |
+----+-------+-------------------+-------------------------+
(2 rows) (0.001s)

heliosdb> \d users  -- Describe table
heliosdb> \dt       -- List all tables
heliosdb> \?        -- Show help
heliosdb> \q        -- Quit

2. Embedded Mode (Rust Applications)

Create a new Rust project:

cargo new my-helios-app
cd my-helios-app

Add HeliosDB Nano to Cargo.toml:

[dependencies]
heliosdb-nano = "0.1.0"

Basic example (src/main.rs):

use heliosdb_nano::{EmbeddedDatabase, Result};

fn main() -> Result<()> {
    // Create embedded database
    let db = EmbeddedDatabase::new("./data.helio")?;

    // Create table
    db.execute("CREATE TABLE products (
        id INT PRIMARY KEY,
        name TEXT,
        price DECIMAL(10,2)
    )")?;

    // Insert data
    db.execute(
        "INSERT INTO products VALUES (1, 'Laptop', 999.99)",
        &[]
    )?;

    // Query data
    let results = db.query("SELECT * FROM products WHERE price > 500", &[])?;

    for row in results {
        println!("Product: {:?}", row);
    }

    Ok(())
}

Run it:

cargo run

3. Server Mode (PostgreSQL-Compatible)

Start HeliosDB Nano as a PostgreSQL-compatible server:

# Initialize database
heliosdb-nano init ./mydb

# Start server
heliosdb-nano start --port 5432 --data ./mydb

# In another terminal, connect with psql
psql postgresql://localhost:5432/mydb

Now you can use any PostgreSQL-compatible tool:

• psql (command-line client)
• pgAdmin (GUI)
• DBeaver (universal database tool)
• SQLAlchemy (Python ORM)
• Prisma (TypeScript ORM)
• Diesel (Rust ORM)

Usage Modes

HeliosDB Nano offers 4 deployment modes to match your application needs:

Mode 1: In-Memory (Fast, No Persistence)

Perfect for:

• Testing and CI/CD pipelines
• Temporary data processing
• Fast analytics on ephemeral data

use heliosdb_nano::EmbeddedDatabase;

let db = EmbeddedDatabase::new_in_memory()?;
// Data lost when program exits

# CLI REPL
heliosdb-nano repl --memory

Pros: Extremely fast, no disk I/O overhead Cons: Data is lost on shutdown

Mode 2: Embedded (In-Process, Persistent)

Perfect for:

• Desktop applications
• Mobile apps (via bindings)
• Edge devices and IoT
• Single-process services

let db = EmbeddedDatabase::new("./mydb.helio")?;
// Data persisted to disk

# CLI REPL
heliosdb-nano repl -d ./mydb

Pros: SQLite-like simplicity, zero configuration Cons: Single-process access only

Mode 3: Server (Network, Persistent)

Perfect for:

• Web applications
• Microservices
• Multi-client scenarios
• PostgreSQL migration

# Start server with persistent storage
heliosdb-nano start --port 5432 --data ./mydb

Pros: Multi-client access, PostgreSQL wire protocol Cons: Network overhead

Mode 4: Hybrid (Server + Memory Cache) ⭐ Production Ready

This is the recommended mode for production applications. Hybrid mode combines:

• ✅ Network access (multi-client support)
• ✅ Persistent storage (data durability)
• ✅ Memory cache (high performance)
• ✅ Configurable cache size

Perfect for:

• Production web applications
• High-traffic microservices
• Systems requiring both performance and durability
• Applications with hot data workloads

Configuration:

heliosdb.toml

[storage]
path = "./heliosdb-data"      # Persistent storage
memory_only = false            # Enable disk persistence
cache_size = 536870912         # 512 MB memory cache

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

[performance]
worker_threads = 8             # Parallel query execution
simd_enabled = true            # SIMD acceleration
parallel_query = true

Start server:

# Using config file (recommended)
heliosdb-nano start --config heliosdb.toml

# Or with CLI flags
heliosdb-nano start --port 5432 \
  --data ./heliosdb-data \
  --cache-size 536870912

Performance tuning:

[storage]
# Adjust cache size based on available RAM
cache_size = 1073741824        # 1 GB for 8GB RAM systems
cache_size = 2147483648        # 2 GB for 16GB RAM systems
cache_size = 4294967296        # 4 GB for 32GB+ RAM systems

# Enable compression for better cache efficiency
compression = "zstd"           # or "lz4" for faster compression

Pros: Best performance + durability + multi-client Cons: Requires more memory (but configurable)

---

Quick Mode Selection:

Need	Use Mode
Testing, CI/CD	In-Memory
Desktop app, single-process	Embedded
Multi-client, basic server	Server
Production, high performance	Hybrid ⭐

📖 For detailed comparison and architecture, see docs/DEPLOYMENT_MODES.md

Common Use Cases

Use Case 1: Web Application (Rust + Axum)

use axum::{routing::get, Router, Json};
use heliosdb_nano::EmbeddedDatabase;
use std::sync::Arc;

#[derive(Clone)]
struct AppState {
    db: Arc<EmbeddedDatabase>,
}

async fn list_users(state: AppState) -> Json<Vec<User>> {
    let results = state.db.query(
        "SELECT id, name, email FROM users",
        &[]
    ).unwrap();

    // Convert to User struct
    Json(results.into_iter().map(User::from).collect())
}

#[tokio::main]
async fn main() {
    let db = Arc::new(EmbeddedDatabase::new("./app.helio").unwrap());

    let app = Router::new()
        .route("/users", get(list_users))
        .with_state(AppState { db });

    axum::Server::bind(&"0.0.0.0:3000".parse().unwrap())
        .serve(app.into_make_service())
        .await
        .unwrap();
}

Use Case 2: AI/ML with Vector Search

use heliosdb_nano::EmbeddedDatabase;

fn main() -> Result<()> {
    let db = EmbeddedDatabase::new("./vectors.helio")?;

    // Create table with vector column
    db.execute("
        CREATE TABLE documents (
            id SERIAL PRIMARY KEY,
            content TEXT,
            embedding VECTOR(1536)  -- OpenAI ada-002 dimension
        )
    ")?;

    // Create HNSW index for fast similarity search
    db.execute("
        CREATE INDEX embedding_idx ON documents
        USING hnsw (embedding vector_cosine_ops)
        WITH (m = 16, ef_construction = 200)
    ")?;

    // Insert document with embedding
    db.execute("
        INSERT INTO documents (content, embedding) VALUES
        ('HeliosDB is fast', $1)
    ", &[vec![0.1, 0.2, 0.3, /* ... 1536 dims */]])?;

    // Semantic search (k-NN)
    let query_embedding = vec![0.15, 0.25, 0.35, /* ... */];
    let results = db.query("
        SELECT id, content,
               embedding <=> $1 AS distance
        FROM documents
        ORDER BY distance
        LIMIT 10
    ", &[query_embedding])?;

    Ok(())
}

Use Case 3: Analytics with JSONB

use heliosdb_nano::EmbeddedDatabase;
use serde_json::json;

fn main() -> Result<()> {
    let db = EmbeddedDatabase::new("./analytics.helio")?;

    // Create table with JSONB column
    db.execute("
        CREATE TABLE events (
            id SERIAL PRIMARY KEY,
            event_type TEXT,
            metadata JSONB,
            created_at TIMESTAMP DEFAULT NOW()
        )
    ")?;

    // Insert events with rich metadata
    db.execute("
        INSERT INTO events (event_type, metadata) VALUES
        ('page_view', $1),
        ('purchase', $2)
    ", &[
        json!({"page": "/home", "user_agent": "Mozilla/5.0"}),
        json!({"amount": 99.99, "currency": "USD", "items": [1, 2, 3]})
    ])?;

    // Query JSONB fields
    let results = db.query("
        SELECT event_type, metadata->>'page' AS page
        FROM events
        WHERE metadata->>'currency' = 'USD'
    ", &[])?;

    Ok(())
}

Use Case 4: Encrypted Storage

heliosdb.toml

[encryption]
enabled = true
algorithm = "aes256-gcm"
key_source = { environment = "HELIOSDB_KEY" }

use heliosdb_nano::{EmbeddedDatabase, Config};

fn main() -> Result<()> {
    // Set encryption key
    std::env::set_var("HELIOSDB_KEY", "your-32-byte-encryption-key-here!!");

    // Load config with encryption
    let config = Config::from_file("heliosdb.toml")?;
    let db = EmbeddedDatabase::with_config("./encrypted.helio", config)?;

    // All data automatically encrypted at rest
    db.execute("CREATE TABLE secrets (key TEXT, value TEXT)")?;
    db.execute("INSERT INTO secrets VALUES ('api_key', 'secret123')")?;

    // Data encrypted in ./encrypted.helio
    Ok(())
}

Configuration

Basic Configuration

Create heliosdb.toml:

[storage]
path = "./heliosdb-data"
cache_size = 536870912  # 512 MB
compression = "zstd"
in_memory = false

[encryption]
enabled = false
algorithm = "aes256-gcm"
key_source = { environment = "HELIOSDB_ENCRYPTION_KEY" }

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

[performance]
enable_simd = true
worker_threads = 4

Load configuration:

use heliosdb_nano::{EmbeddedDatabase, Config};

let config = Config::from_file("heliosdb.toml")?;
let db = EmbeddedDatabase::with_config("./mydb", config)?;

Troubleshooting

Issue: “Database locked”

Cause: Another process is using the database.

Solution: Ensure only one process accesses the database at a time in embedded mode. Use server mode for multi-client access.

Issue: “Out of memory”

Cause: Large query result set.

Solution: Use LIMIT/OFFSET for pagination:

SELECT * FROM large_table LIMIT 100 OFFSET 0;

Issue: “Permission denied”

Cause: Insufficient file system permissions.

Solution: Check directory permissions:

chmod 755 ./heliosdb-data

Issue: Query performance slow

Solutions:

1. Add indexes: CREATE INDEX idx_name ON table (column);
2. Use EXPLAIN: EXPLAIN SELECT * FROM table WHERE ...;
3. Enable SIMD: Set enable_simd = true in config
4. Increase cache: Set cache_size to larger value

Next Steps

Learn More

• SQL Reference - Complete SQL syntax guide
• Vector Database Guide - Deep dive into vector search
• Encryption Guide - Secure your data
• API Reference - Complete Rust API docs

Examples

Check out the examples/ directory:

• examples/embedded.rs - Basic embedded usage
• examples/vector_search_demo.rs - Vector search walkthrough
• examples/encryption_demo.rs - Encryption setup
• examples/complex_queries_demo.rs - Advanced SQL
• examples/repl_demo.md - REPL usage guide

ORM Integration

• SQLAlchemy (Python): See docs/ORM_SUPPORT.md
• Diesel (Rust): See docs/ORM_SUPPORT.md
• Prisma (TypeScript): See docs/ORM_SUPPORT.md

Community & Support

• GitHub Issues: https://github.com/heliosdb/heliosdb/issues
• Discussions: https://github.com/heliosdb/heliosdb/discussions
• Discord: https://discord.gg/heliosdb (coming soon)

Quick Reference

SQL Commands

-- Tables
CREATE TABLE name (col TYPE, ...);
DROP TABLE name;
ALTER TABLE name ADD COLUMN col TYPE;

-- Data
INSERT INTO table VALUES (...);
UPDATE table SET col = val WHERE ...;
DELETE FROM table WHERE ...;
SELECT * FROM table WHERE ... ORDER BY ... LIMIT 10;

-- Indexes
CREATE INDEX idx_name ON table (column);
CREATE INDEX idx_vector ON table USING hnsw (embedding vector_cosine_ops);

-- Transactions
BEGIN;
COMMIT;
ROLLBACK;

REPL Meta-Commands

\d [table]      Describe table (or list all tables if no arg)
\dt             List all tables
\di             List all indexes
\?              Show help
\h [command]    Show SQL command help
\q              Quit

Rust API

// Database operations
let db = EmbeddedDatabase::new(path)?;
db.execute(sql, params)?;
let results = db.query(sql, params)?;

// Transactions
let tx = db.begin_transaction()?;
tx.execute(sql, params)?;
tx.commit()?;  // or tx.rollback()?

// Configuration
let config = Config::from_file(path)?;
let db = EmbeddedDatabase::with_config(path, config)?;

---

Ready to build? Jump into the examples or check out the API docs!