HeliosDB Nano User Adoption Guide

Introduction
Getting Started
Core Concepts
Implementation Guide
Best Practices
Troubleshooting
Support & Community

Introduction

HeliosDB Nano is a PostgreSQL-compatible embedded database designed for developers who need a SQL database without the operational overhead of managing a separate database server.

Key Benefits

Zero Configuration: Works out of the box, no setup required
PostgreSQL Compatible: Use existing PostgreSQL tools and libraries
Embedded: Deploy with your application as a single binary
Vector Search: Built-in semantic search capabilities
Encryption: Transparent encryption at rest
Time-Travel: Query historical data with temporal queries
Branching: Git-like workflows for schema changes

Who Should Use HeliosDB Nano?

Ideal for:

Embedded applications (desktop, mobile, IoT)
Microservices with local storage needs
AI/ML applications requiring vector search
Edge computing and offline-first apps
Development and testing environments
Applications needing git-like database branching

Consider alternatives if you need:

Multi-node clustering (see full HeliosDB platform)
Extremely high write throughput (>100K writes/sec)
Distributed transactions across nodes

Getting Started

Quick 5-Minute Start

Option 1: Try the REPL (No Installation)

# Official image (linux/amd64 + linux/arm64)
docker run -it --rm ghcr.io/heliosdatabase/heliosdb-nano:latest repl --memory   # pin a release tag in production

# Or after installing via cargo
heliosdb-nano repl --memory

Interactive session example:

heliosdb> CREATE TABLE products (
  id SERIAL PRIMARY KEY,
  name TEXT,
  price DECIMAL(10,2)
);

heliosdb> INSERT INTO products (name, price) VALUES ('Widget', 29.99);

heliosdb> SELECT * FROM products;

Option 2: Embed in Your Application (Rust)

Create Cargo.toml:

[dependencies]
heliosdb-nano = "4"

Create src/main.rs:

use heliosdb_nano::EmbeddedDatabase;

fn main() -> Result<(), Box<dyn std::error::Error>> {
    let db = EmbeddedDatabase::new("./myapp.helio")?;

    db.execute("CREATE TABLE IF NOT EXISTS users (
        id INT PRIMARY KEY,
        name TEXT,
        email TEXT
    )")?;

    db.execute("INSERT INTO users VALUES ($1, $2, $3)",
        &[1, "Alice", "alice@example.com"])?;

    let results = db.query("SELECT * FROM users", &[])?;
    println!("{:?}", results);

    Ok(())
}

Run: cargo run

Option 3: Server Mode (PostgreSQL Compatible)

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

# Connect with any PostgreSQL client
psql postgresql://localhost:5432/mydb

Core Concepts

1. Deployment Modes

HeliosDB Nano supports 4 deployment modes:

Embedded (In-Process)

Data location: Application process memory + disk
Concurrency: Single process only
Best for: Desktop apps, mobile apps, single-server microservices
Setup time: <5 minutes

Server (Network)

Data location: Separate server process, accessed via TCP
Concurrency: Multiple clients
Best for: Web apps, multi-service architectures
Setup time: <10 minutes

In-Memory (Temporary)

Data location: RAM only by default; from the command prompt, add --dump-on-shutdown for a graceful-exit dump
Concurrency: Single process
Best for: Tests, temporary analytics
Setup time: <1 minute

Hybrid (Recommended for Production)

Data location: Persistent disk + memory cache
Concurrency: Multiple clients via server
Performance: High (cached data)
Durability: Full (persisted data)
Best for: Production applications
Setup time: 15 minutes

2. SQL Operations

HeliosDB Nano uses standard PostgreSQL SQL:

-- Table creation
CREATE TABLE orders (
    id SERIAL PRIMARY KEY,
    customer_id INT,
    total DECIMAL(10,2),
    created_at TIMESTAMP DEFAULT NOW()
);

-- Data insertion
INSERT INTO orders (customer_id, total)
VALUES (123, 99.99);

-- Parameterized queries (safe from SQL injection)
SELECT * FROM orders WHERE customer_id = $1;

-- Aggregations
SELECT COUNT(*) as order_count, SUM(total) as revenue
FROM orders
GROUP BY customer_id;

3. Advanced Features

Vector Search (Semantic Search)

Store and search documents by semantic similarity:

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

-- Create index for fast search
CREATE INDEX embedding_idx ON documents
USING hnsw (embedding vector_cosine_ops)
WITH (m = 16, ef_construction = 200);

-- Insert document with embedding
INSERT INTO documents (title, content, embedding)
VALUES ('HeliosDB Guide', 'Complete guide...', $1);

-- Semantic search (find similar documents)
SELECT id, title, embedding <=> $1 AS similarity
FROM documents
ORDER BY similarity
LIMIT 10;

Time-Travel Queries (Historical Data)

Query data as it existed at any point in time:

-- Current data
SELECT * FROM products WHERE id = 1;

-- Data as of yesterday
SELECT * FROM products AS OF TIMESTAMP '2025-01-13 12:00:00'
WHERE id = 1;

-- Compare current vs historical
SELECT
    current.price AS current_price,
    historical.price AS previous_price
FROM products current
JOIN products AS OF TIMESTAMP '2025-01-13 00:00:00' historical
    ON current.id = historical.id
WHERE current.price <> historical.price;

Database Branching (Git-Like Workflows)

Create isolated branches for testing schema changes:

-- Create a branch from main
CREATE BRANCH development FROM main;

-- Switch to branch
USE BRANCH development;

-- Make experimental changes
ALTER TABLE users ADD COLUMN preferences JSONB;
INSERT INTO users VALUES (999, 'Test User', '{}');

-- Test your changes
SELECT * FROM users WHERE id = 999;

-- If satisfied, merge back
USE BRANCH main;
MERGE BRANCH development INTO main;

-- Clean up
DROP BRANCH development;

Materialized Views (Pre-Computed Results)

Create views that are automatically refreshed:

-- Create materialized view (computed result)
CREATE MATERIALIZED VIEW sales_by_month AS
SELECT
    DATE_TRUNC('month', order_date) as month,
    SUM(amount) as total_sales,
    COUNT(*) as order_count
FROM orders
GROUP BY DATE_TRUNC('month', order_date);

-- Query returns instant results (pre-computed)
SELECT * FROM sales_by_month;

-- Configure auto-refresh
ALTER MATERIALIZED VIEW sales_by_month SET (
    auto_refresh = true,
    staleness_threshold_sec = 300  -- Refresh if older than 5 min
);

-- Manual refresh if needed
REFRESH MATERIALIZED VIEW sales_by_month;

Implementation Guide

Step 1: Planning (5-10 minutes)

Identify your use case (see Getting Started)
Choose deployment mode (Embedded, Server, or Hybrid)
List required tables and columns
Identify any encryption requirements

Step 2: Setup (10-30 minutes)

For Rust Applications:

Add dependency to Cargo.toml
Initialize database at application startup
Run schema creation on first start
Test with sample data

For Server Mode:

Initialize database: heliosdb-nano init./mydb
Configure heliosdb.toml if needed
Start server: heliosdb-nano start --port 5432 --data./mydb
Connect with PostgreSQL client

For Non-Rust Applications: Use server mode and connect via PostgreSQL wire protocol with your preferred driver.

Step 3: Development (Application-specific)

Define your schema:

-- Example: E-commerce application schema
CREATE TABLE customers (
    id SERIAL PRIMARY KEY,
    email TEXT UNIQUE NOT NULL,
    name TEXT,
    created_at TIMESTAMP DEFAULT NOW()
);

CREATE TABLE products (
    id SERIAL PRIMARY KEY,
    name TEXT NOT NULL,
    description TEXT,
    price DECIMAL(10,2),
    category TEXT,
    embedding VECTOR(1536)  -- For semantic search
);

CREATE TABLE orders (
    id SERIAL PRIMARY KEY,
    customer_id INT REFERENCES customers(id),
    created_at TIMESTAMP DEFAULT NOW(),
    total DECIMAL(10,2)
);

CREATE TABLE order_items (
    order_id INT REFERENCES orders(id),
    product_id INT REFERENCES products(id),
    quantity INT,
    unit_price DECIMAL(10,2),
    PRIMARY KEY (order_id, product_id)
);

-- Create indexes for common queries
CREATE INDEX idx_customer_email ON customers(email);
CREATE INDEX idx_order_customer ON orders(customer_id);
CREATE INDEX idx_product_category ON products(category);

-- Create search index
CREATE INDEX idx_product_embedding ON products
USING hnsw (embedding vector_cosine_ops);

Step 4: Deployment

Single-Server Deployment:

# Start in production mode
heliosdb-nano start \
    --port 5432 \
    --data-dir ./production-data \
    --config heliosdb.toml

# Connection string for applications
postgresql://user:password@localhost:5432/mydb

Containerized Deployment:

# Pin a release tag in production
FROM ghcr.io/heliosdatabase/heliosdb-nano:latest

# Copy your configuration
COPY heliosdb.toml /app/heliosdb.toml

# Start server. The entrypoint runs heliosdb-nano and, unless you pass --auth,
# enables scram-sha-256 with the password from HELIOSDB_PASSWORD (or
# HELIOSDB_PASSWORD_FILE) supplied at `docker run` time. It also keeps the HTTP
# listener on 127.0.0.1 unless you pass --http-listen or set HELIOSDB_HTTP_LISTEN.
CMD ["start", "--data-dir", "/data", "--listen", "0.0.0.0", "--config", "/app/heliosdb.toml"]

Keep the HTTP and MySQL listeners on loopback (the default): API-key authentication for the HTTP API is planned, and a smaller listening surface is good practice anyway.

Best Practices

1. Connection Management

In Embedded Mode:

// Initialize once, reuse connection
let db = Arc::new(EmbeddedDatabase::new("./app.helio")?);

// Share across threads
let db_clone = Arc::clone(&db);
thread::spawn(move || {
    let results = db_clone.query("SELECT * FROM users", &[])?;
});

In Server Mode:

// Use connection pooling
use sqlx::postgres::PgPoolOptions;

let pool = PgPoolOptions::new()
    .max_connections(10)
    .connect("postgresql://localhost:5432/mydb")
    .await?;

2. Data Safety

Always use parameterized queries:

// SAFE: Parameterized query
db.query("SELECT * FROM users WHERE id = $1", &[user_id])?;

// UNSAFE: String interpolation
db.query(&format!("SELECT * FROM users WHERE id = {}", user_id), &[])?;

3. Performance Optimization

Index frequently queried columns:

CREATE INDEX idx_user_email ON users(email);
CREATE INDEX idx_order_date ON orders(created_at);

Use EXPLAIN to analyze queries:

EXPLAIN SELECT * FROM orders WHERE customer_id = 123;

Batch operations:

// Good: Batch insert
db.execute("BEGIN TRANSACTION")?;
for item in items {
    db.execute("INSERT INTO products VALUES ($1, $2, $3)",
        &[item.id, item.name, item.price])?;
}
db.execute("COMMIT")?;

// Less efficient: Individual transactions
for item in items {
    db.execute("INSERT INTO products VALUES ($1, $2, $3)",
        &[item.id, item.name, item.price])?;  // Auto-commit each
}

4. Backup Strategy

Regular backups:

# Embedded mode: copy database file
cp ./myapp.helio ./myapp.helio.backup.$(date +%Y%m%d)

# Server mode: use pg_dump
pg_dump postgresql://localhost:5432/mydb > backup.sql

# Or use built-in export
heliosdb-nano export ./mydb > backup.sql

5. Monitoring

Check database health:

-- Check database size
SELECT pg_database_size(current_database()) as db_size;

-- List all tables
SELECT * FROM information_schema.tables
WHERE table_schema = 'public';

-- Check index usage
SELECT * FROM pg_stat_user_indexes;

-- Monitor slow queries
SET log_min_duration_statement = 1000;  -- Log queries > 1 second

Troubleshooting

Common Issues

”Database locked” error in embedded mode

Cause: Multiple processes accessing database simultaneously

Solution:

Use server mode for multi-process access
Ensure only one application instance uses embedded database

”Out of memory” error

Cause: Query result too large or insufficient cache

Solution:

# Increase cache size in heliosdb.toml
[storage]
cache_size = 1073741824  # 1 GB

# Or paginate results in application
SELECT * FROM large_table LIMIT 100 OFFSET 0;

Slow vector search queries

Cause: Missing index or poor vector quantization settings

Solution:

-- Ensure index exists
CREATE INDEX idx_embeddings ON documents
USING hnsw (embedding vector_cosine_ops)
WITH (m = 16, ef_construction = 200);

-- For better performance, enable Product Quantization
WITH (quantization = 'product', pq_subquantizers = 8);

Connection refused in server mode

Cause: Server not running or wrong port

Solution:

# Verify server is running
ps aux | grep heliosdb-nano

# Check if port is in use
lsof -i :5432

# Start with verbose logging
RUST_LOG=debug heliosdb-nano start --port 5432 --data-dir ./mydb

Support & Community

Documentation Resources

SQL Reference - Complete SQL documentation
API Reference - Rust API documentation

Getting Help

Check troubleshooting guidance for documented limitations
Search existing issues on GitHub
Create a new issue with:
- Minimal reproduction case
- Version: heliosdb-nano --version
- Rust version: rustc --version (if using embedded mode)
Join discussions on Discord

Reporting Issues

Include the following when reporting issues:

HeliosDB Nano version
Operating system
Steps to reproduce
Expected vs actual behavior
Relevant code or SQL

Next Steps

Try it out: Run heliosdb-nano repl --memory
Follow a tutorial: Choose your use case from examples
Build your first app: Start with embedded mode or server mode
Explore advanced features: Vector search, branching, time-travel
Join the community: Discuss on Discord

Ready to dive deeper? Check out the getting started guide or explore examples.

HeliosDB Nano User Adoption Guide

Table of Contents

Introduction

Key Benefits

Who Should Use HeliosDB Nano?

Getting Started

Quick 5-Minute Start

Option 1: Try the REPL (No Installation)

Option 2: Embed in Your Application (Rust)

Option 3: Server Mode (PostgreSQL Compatible)

Core Concepts

1. Deployment Modes

Embedded (In-Process)

Server (Network)

In-Memory (Temporary)

Hybrid (Recommended for Production)

2. SQL Operations

3. Advanced Features

Vector Search (Semantic Search)

Time-Travel Queries (Historical Data)

Database Branching (Git-Like Workflows)

Materialized Views (Pre-Computed Results)

Implementation Guide

Step 1: Planning (5-10 minutes)

Step 2: Setup (10-30 minutes)

Step 3: Development (Application-specific)

Step 4: Deployment

Best Practices

1. Connection Management

2. Data Safety

3. Performance Optimization

4. Backup Strategy

5. Monitoring

Troubleshooting

Common Issues

”Database locked” error in embedded mode

”Out of memory” error

Slow vector search queries

Connection refused in server mode

Support & Community

Documentation Resources

Getting Help

Reporting Issues

Next Steps