---
title: "HeliosDB Nano Quick Start Guide"
---

# HeliosDB Nano Quick Start Guide

## Installation

```bash
# Build from source
git clone https://github.com/HeliosDatabase/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)

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

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

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

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

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

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

### Branching, Snapshots and Views
```
\branches       List database branches
\snapshots      List time-travel snapshots
\dmv            List materialized views
\compression    Show compression statistics
```

### Settings and Statistics
```
\set            Show all settings
\config         Show configuration
\stats          Show database statistics
\optimize <t>   Optimization recommendations
```

## Essential SQL Commands

### Settings Management
```sql
-- 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
```sql
-- 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
```sql
-- 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
```sql
-- 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
```sql
-- 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
```sql
-- Set compression for table
ALTER TABLE large_table SET COMPRESSION zstd;

-- Check compression stats
\compression large_table
```

## Configuration File

### Basic Configuration (config.toml)

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

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

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

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

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

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

1. **Enable timing to identify slow queries:**
   ```
   \timing
   ```

2. **Use EXPLAIN to understand query plans:**
   ```sql
   EXPLAIN SELECT * FROM large_table WHERE id > 1000;
   ```

3. **Set appropriate timeouts:**
   ```sql
   SET statement_timeout = 30000; -- 30 seconds
   ```

4. **Tune memory for workload:**
   ```sql
   -- Analytics: more memory
   SET work_mem = 131072; -- 128MB

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

5. **Use compression for large tables:**
   ```sql
   ALTER TABLE logs SET COMPRESSION zstd;
   ```

6. **Create materialized views for expensive queries:**
   ```sql
   CREATE MATERIALIZED VIEW expensive_query AS
     SELECT... complex query...
     WITH (auto_refresh = true);
   ```

## Troubleshooting

### Query too slow

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

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

```bash
# Check server status
\server status

# Check configuration
\config

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

## Next Steps

1. **Read the documentation:**
   - [REPL Command Reference](https://www.heliosdb.com/docs/nano/guides/user/guides/user/repl_command_reference/)
   - [SQL Settings Reference](https://www.heliosdb.com/docs/nano/guides/user/guides/user/sql_settings_reference/)
   - [Configuration File Reference](https://www.heliosdb.com/docs/nano/guides/user/guides/user/config_file_reference/)

2. **Explore features:**
   - Time-travel queries
   - Database branching
   - Materialized views
   - Vector search

3. **Optimize performance:**
   - Use EXPLAIN for query plans
   - Create appropriate indexes
   - Tune memory settings
   - Enable compression

   - 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/HeliosDatabase/HeliosDB-Nano
- **Issues**: https://github.com/HeliosDatabase/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` | - | - |

---

Start with `\h` in the REPL.