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

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

./target/release/heliosdb-nano repl

Features: Live database for experimentation Time: Unlimited Best for: Hands-on exploration

⏱️ 5-Minute Quick Demo

./target/release/heliosdb-nano repl

Then run these commands:

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

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

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

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

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

Run the interactive tutorial
Read the branches and time-travel tutorial
Experiment in REPL

For Production Workflows

Read the branching guide for merge and cleanup patterns
Combine time-travel queries with branch recovery points
Review deployment mode guidance before exposing a server port

🔗 All Resources

Tutorials:

Branches and time-travel tutorial - Comprehensive 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

Start with the interactive tutorial if you’re new to time-travel
Create a disposable branch before testing destructive changes
Read examples in the tutorial for advanced patterns
Use AS OF TIMESTAMP for human-readable recovery points

🆘 Troubleshooting

“Binary not found”

cargo build --release

“Table already exists” (in tests)

rm -f heliosdb.db*  # Clean up old database
cargo test branch_sql_integration_tests

“Connection refused”

pkill -f heliosdb-nano
rm -f heliosdb.db*
./target/release/heliosdb-nano repl

📈 Performance

System views: <1ms (ultra-fast)
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

Happy time-traveling! 🕐