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

# HeliosDB Nano Quick Start Guide

Get started with time-travel queries, database branching, and system views in 5 minutes.

---

## Instant Start (Choose One)

### Option 1: Interactive Tutorial (Recommended for Learning)
Run the interactive tutorial script from the Nano scripts directory.
**Features**: Guided walkthrough with explanations, examples, and pause points
**Time**: ~15-20 minutes
**Best for**: Understanding concepts from scratch

### Option 2: Automated Tests
```bash
cargo test branch_sql_integration_tests
```
**Features**: 20 automated tests covering all features
**Time**: ~2-3 minutes
**Best for**: Validating features work

### Option 3: REPL Playground
```bash
./target/release/heliosdb-nano repl
```
**Features**: Live database for experimentation
**Time**: Unlimited
**Best for**: Hands-on exploration

---

## 5-Minute Quick Demo

```bash
./target/release/heliosdb-nano repl
```

Then run these commands:

```sql
-- 1. Create a table
CREATE TABLE users (id INT, name TEXT, status TEXT);

-- 2. Insert some data
INSERT INTO users VALUES (1, 'Alice', 'active');

-- 3. Query current state
SELECT * FROM users AS OF NOW;

-- 4. Query a historical timestamp
SELECT * FROM users AS OF TIMESTAMP '2025-11-28 09:00:00';

-- 5. Query by transaction
SELECT * FROM users AS OF TRANSACTION 1;

-- 6. Create and inspect a branch
CREATE DATABASE BRANCH quick_demo FROM main AS OF NOW;
SELECT * FROM pg_database_branches();

-- 7. Switch, return, merge, and remove the branch
USE BRANCH quick_demo;
USE BRANCH main;
MERGE DATABASE BRANCH quick_demo INTO main WITH (delete_branch_after = true);

-- 8. Exit
\q
```

**Expected**: All queries succeed and return results

---

## Learning Resources

| Resource | Duration | Best For |
|----------|----------|----------|
| **Interactive tutorial** | 15-20 min | Learning concepts step-by-step |
| **Branches and Time-Travel Tutorial** | 20-30 min | Reading explanations and examples |
| **features/branching.md** | 10 min | Branch lifecycle and merge syntax |
| **features/time-travel.md** | 10 min | Historical query patterns |

---

## What You Can Do Now

### Time-Travel Queries
```sql
-- Query at specific timestamp
SELECT * FROM table AS OF TIMESTAMP '2025-11-28 09:00:00';

-- Query after specific transaction
SELECT * FROM table AS OF TRANSACTION 5;

-- Query with system change number
SELECT * FROM table AS OF SCN 1000;

-- Query current state (explicit)
SELECT * FROM table AS OF NOW;
```

### System Views
```sql
-- View database branch info
SELECT * FROM pg_database_branches();

-- View materialized view staleness
SELECT * FROM pg_mv_staleness();

-- View vector index statistics
SELECT * FROM pg_vector_index_stats();
```

### Database Branching
```sql
-- Create a branch from main
CREATE DATABASE BRANCH feature_dev FROM main AS OF NOW;

-- Work in the branch
USE BRANCH feature_dev;

-- Return to main and merge
USE BRANCH main;
MERGE DATABASE BRANCH feature_dev INTO main
WITH (conflict_resolution = 'branch_wins');

-- Drop abandoned branches
DROP DATABASE BRANCH IF EXISTS feature_dev;
```

### Advanced Features
```sql
-- Time-travel with WHERE clause
SELECT * FROM orders
AS OF TIMESTAMP '2025-11-28 09:00:00'
WHERE amount > 1000;

-- Time-travel with aggregates
SELECT COUNT(*), SUM(amount) FROM sales
AS OF TIMESTAMP '2025-11-28 12:00:00';

-- Compare data at different times (UNION)
SELECT 'Current', COUNT(*) as users FROM users
UNION ALL
SELECT '24h ago', COUNT(*) FROM users
  AS OF TIMESTAMP '2025-11-27 09:00:00';
```

---

## Next Steps

### For Learning
1. Run the interactive tutorial
2. Read the branches and time-travel tutorial
3. Experiment in REPL

### For Production Workflows
1. Read the branching guide for merge and cleanup patterns
2. Combine time-travel queries with branch recovery points
3. Review deployment mode guidance before exposing a server port

---

## All Resources

**Tutorials**:
- Branches and time-travel tutorial - Guide
- Interactive tutorial script - Interactive walkthrough (with pause function)

**Documentation**:
- `features/branching.md` - Branch lifecycle and merge options
- `features/time-travel.md` - Historical queries

**Quick Reference**:
- `QUICK_START.md` - This file

---

## Tips

1. **Start with the interactive tutorial** if you're new to time-travel
2. **Create a disposable branch** before testing destructive changes
3. **Read examples** in the tutorial for advanced patterns
4. **Use `AS OF TIMESTAMP`** for human-readable recovery points

---

## Troubleshooting

**"Binary not found"**
```bash
cargo build --release
```

**"Table already exists"** (in tests)
```bash
rm -f heliosdb.db*  # Clean up old database
cargo test branch_sql_integration_tests
```

**"Connection refused"**
```bash
pkill -f heliosdb-nano
rm -f heliosdb.db*
./target/release/heliosdb-nano repl
```

---

## Performance

- **System views**: <1ms
- **Time-travel queries**: <100ms (responsive)
- **Branch creation**: metadata-only copy-on-write setup

---

## Quick Checklist

- [ ] Read this file
- [ ] Run the interactive tutorial
- [ ] Try manual commands in REPL
- [ ] Read the branches and time-travel tutorial
- [ ] Create, merge, and drop a disposable branch