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

# Getting Started with HeliosDB Nano

This guide gets HeliosDB Nano running in about 5 minutes.

## Table of Contents

- [Installation](#installation)
- [Quick Start](#quick-start)
- [Usage Modes](#usage-modes)
- [Common Use Cases](#common-use-cases)
- [Next Steps](#next-steps)

## Installation

### Prerequisites

- **Rust** 1.85+ (for building from source)
- **Operating System**: Linux, macOS, or Windows

### Option 1: Prebuilt Binary or Cargo

Download a binary for your platform from [GitHub Releases](https://github.com/HeliosDatabase/HeliosDB-Nano/releases/latest), or install with `cargo install heliosdb-nano --locked`.

### Option 1b: Build from Source

```bash
git clone https://github.com/HeliosDatabase/HeliosDB-Nano.git
cd HeliosDB-Nano
cargo build --release

# Optional: install the local build into your Cargo bin directory
cargo install --path .
```

### Option 2: Docker

```bash
# Server: password auth is required on the container's 0.0.0.0 listener
# (latest shown; pin a release tag in production)
docker run -d --name heliosdb -p 5432:5432 \
  -e HELIOSDB_PASSWORD=change-me \
  -v heliosdb_data:/data \
  ghcr.io/heliosdatabase/heliosdb-nano:latest

psql "postgresql://postgres:change-me@localhost:5432/postgres?sslmode=require" -c 'SELECT 1'

# Or an interactive in-memory REPL
docker run -it --rm ghcr.io/heliosdatabase/heliosdb-nano:latest repl --memory
```

The image is multi-arch (linux/amd64, linux/arm64), runs as uid 999 and
generates a self-signed TLS certificate in `/data/tls` on first start. Its
HTTP API (port 8080) does not use the database password, so it stays on the
container's loopback unless you set `HELIOSDB_HTTP_LISTEN=0.0.0.0`.

## Quick Start

### 1. Interactive REPL (Fastest Way to Try)

```bash
# Start in-memory database; add --dump-on-shutdown to dump on exit
heliosdb-nano repl --memory

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

Example session:

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

```bash
cargo new my-helios-app
cd my-helios-app
```

Add HeliosDB Nano to `Cargo.toml`:

```toml
[dependencies]
heliosdb-nano = "4"
```

Basic example (`src/main.rs`):

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

```bash
cargo run
```

### 3. Server Mode (PostgreSQL-Compatible)

Start HeliosDB Nano as a PostgreSQL-compatible server:

```bash
# Initialize database
heliosdb-nano init ./mydb

# Start server
heliosdb-nano start --port 5432 --data-dir ./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)

Good fit for:
- Testing and CI/CD pipelines
- Temporary data processing
- Fast analytics on ephemeral data

```rust
use heliosdb_nano::EmbeddedDatabase;

let db = EmbeddedDatabase::new_in_memory()?;
// RAM-only by default; use the CLI --dump-on-shutdown option when you need a shutdown dump.
```

```bash
# CLI REPL
heliosdb-nano repl --memory
# CLI REPL with a graceful-exit dump
heliosdb-nano repl --memory --dump-on-shutdown --dump-file ./session.heliodump
```

**Pros:** Extremely fast, no disk I/O overhead
**Cons:** Data is RAM-only unless you enable a shutdown dump with `--dump-on-shutdown`

### Mode 2: Embedded (In-Process, Persistent)

Good fit for:
- Desktop applications
- Mobile apps (via bindings)
- Edge devices and IoT
- Single-process services

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

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

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

### Mode 3: Server (Network, Persistent)

Good fit for:
- Web applications
- Microservices
- Multi-client scenarios
- PostgreSQL migration

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

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

### Mode 4: Hybrid (Server + Memory Cache) **operationally hardened**

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

Good fit for:
- Production web applications
- High-traffic microservices
- Systems requiring both performance and durability
- Applications with hot data workloads

**Configuration:**

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

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

# Or with CLI flags
heliosdb-nano start --port 5432 \
  --data-dir ./heliosdb-data
# (cache size and other storage tuning are set in the config file)
```

**Performance tuning:**

```toml
[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** (recommended) |

For detailed comparison and architecture, see [docs/DEPLOYMENT_MODES.md](https://www.heliosdb.com/docs/nano/guides/docs/deployment_modes/)

## Common Use Cases

### Use Case 1: Web Application (Rust + Axum)

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

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

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

```toml
# heliosdb.toml
[encryption]
enabled = true
algorithm = "aes256-gcm"
key_source = { environment = "HELIOSDB_KEY" }
```

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

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

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

```sql
SELECT * FROM large_table LIMIT 100 OFFSET 0;
```

### Issue: "Permission denied"

**Cause**: Insufficient file system permissions.

**Solution**: Check directory permissions:

```bash
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](https://www.heliosdb.com/docs/nano/guides/docs/sql_reference/)** - Complete SQL syntax guide
- **[API Reference](https://docs.rs/heliosdb-nano)** - 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/HeliosDatabase/HeliosDB-Nano/issues
- **Discord**: https://discord.gg/yTykuUrFXc

## Quick Reference

### SQL Commands

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

```rust
// 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)?;
```

---

Next, see the examples or the [API docs](https://docs.rs/heliosdb-nano).