HeliosDB Nano Phase 3 - Quick Start Guide

Get started with Phase 3 features in 5 minutes!

🚀 Instant Start (Choose One)

Option 1: Interactive Tutorial (Recommended for Learning)

./interactive_phase3_tutorial.sh

Features: Guided walkthrough with explanations, examples, and pause points Time: ~15-20 minutes Best for: Understanding concepts from scratch

Option 2: Automated Tests

./test_phase3_clean.sh

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. View system metadata
SELECT * FROM pg_database_branches();

-- 7. Exit
\q

Expected: All queries succeed and return results

📚 Learning Resources

Resource	Duration	Best For
interactive_phase3_tutorial.sh	15-20 min	Learning concepts step-by-step
PHASE3_TUTORIAL.md	20-30 min	Reading explanations and examples
TESTING_GUIDE.md	10 min	Understanding testing
PHASE3_TEST_RESULTS.md	10 min	Seeing test metrics
PHASE3_PROGRESS_SUMMARY.md	15 min	Implementation details

✨ 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();

✅ 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';

⏳ Coming Soon

Database Branching SQL: CREATE/DROP/MERGE DATABASE BRANCH
Branch Management: List, compare, and manage branches via SQL
Materialized View SQL: Full SQL support for MV operations

📊 Test Results

17/20 tests passing (85%)

Feature	Status	Tests
System Views	✅ 100%	3/3
AS OF NOW	✅ 100%	3/3
AS OF TIMESTAMP	✅ 100%	3/3
AS OF TRANSACTION	✅ 100%	3/3
AS OF SCN	✅ 100%	3/3
Basic SQL	⚠️ 60%	3/5

🎯 Next Steps

For Learning

Run ./interactive_phase3_tutorial.sh
Read PHASE3_TUTORIAL.md
Experiment in REPL

For Development

Review PHASE3_PROGRESS_SUMMARY.md
Check PHASE3_TEST_RESULTS.md
Look at implementation in src/sql/

For Testing

Run ./test_phase3_clean.sh
Read TESTING_GUIDE.md
Try manual tests in REPL

🔗 All Resources

Tutorials:

PHASE3_TUTORIAL.md - Comprehensive guide
interactive_phase3_tutorial.sh - Interactive walkthrough (with pause function)

Testing:

test_phase3_clean.sh - Automated test suite
test_phase3_features.sh - Extended tests
TESTING_GUIDE.md - Test reference

Documentation:

PHASE3_PROGRESS_SUMMARY.md - Implementation status
PHASE3_TEST_RESULTS.md - Test metrics and performance

Quick Reference:

QUICK_START.md - This file

💡 Tips

Start with the interactive tutorial if you’re new to time-travel
Run tests to verify everything works
Read examples in PHASE3_TUTORIAL.md for advanced patterns
Check TESTING_GUIDE.md for troubleshooting

🆘 Troubleshooting

“Binary not found”

cargo build --release

“Table already exists” (in tests)

rm -f heliosdb.db*  # Clean up old database
./test_phase3_clean.sh

“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)
Full test suite: ~2-3 minutes

✅ Quick Checklist

Status: Phase 3 Beta Ready ✅ Last Updated: 2025-11-28 Phase 3 Completion: 85%

Happy time-traveling! 🕐