---
title: "HeliosDB Nano User Adoption Guide"
---

# HeliosDB Nano User Adoption Guide

## Table of Contents

1. [Introduction](#introduction)
2. [Getting Started](#getting-started)
3. [Core Concepts](#core-concepts)
4. [Implementation Guide](#implementation-guide)
5. [Best Practices](#best-practices)
6. [Troubleshooting](#troubleshooting)
7. [Support & Community](#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)

```bash
# 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:
```sql
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`:
```toml
[dependencies]
heliosdb-nano = "4"
```

Create `src/main.rs`:
```rust
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)

```bash
# 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:

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

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

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

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

```sql
-- 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:**
1. Add dependency to `Cargo.toml`
2. Initialize database at application startup
3. Run schema creation on first start
4. Test with sample data

**For Server Mode:**
1. Initialize database: `heliosdb-nano init./mydb`
2. Configure `heliosdb.toml` if needed
3. Start server: `heliosdb-nano start --port 5432 --data./mydb`
4. 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:

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

```bash
# 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:**

```dockerfile
# 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:**
```rust
// 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:**
```rust
// 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:**

```rust
// 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:**
```sql
CREATE INDEX idx_user_email ON users(email);
CREATE INDEX idx_order_date ON orders(created_at);
```

**Use EXPLAIN to analyze queries:**
```sql
EXPLAIN SELECT * FROM orders WHERE customer_id = 123;
```

**Batch operations:**
```rust
// 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:**

```bash
# 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:

```sql
-- 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**:
```toml
# 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**:
```sql
-- 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**:
```bash
# 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](https://www.heliosdb.com/docs/nano/user-guide/sql-reference/)** - Complete SQL documentation
- **[API Reference](https://docs.rs/heliosdb-nano)** - Rust API documentation

### Getting Help

1. Check troubleshooting guidance for documented limitations
2. **Search existing issues** on GitHub
3. **Create a new issue** with:
   - Minimal reproduction case
   - Version: `heliosdb-nano --version`
   - Rust version: `rustc --version` (if using embedded mode)
4. **Join discussions** on [Discord](https://discord.gg/yTykuUrFXc)

### 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

1. **Try it out**: Run `heliosdb-nano repl --memory`
2. **Follow a tutorial**: Choose your use case from examples
3. **Build your first app**: Start with embedded mode or server mode
4. **Explore advanced features**: Vector search, branching, time-travel
5. **Join the community**: Discuss on [Discord](https://discord.gg/yTykuUrFXc)

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