Skip to content
HeliosDB HeliosDB Nano

Phase 3 Testing Guide

Phase 3 Testing Guide

Quick reference for testing Phase 3 features in HeliosDB Nano.

Quick Start

Run All Tests

Terminal window
cd /home/claude/HeliosDB Nano
./test_phase3_clean.sh

Expected Result: 17/20 tests pass (85%)

Run REPL Manually

Terminal window
./target/release/heliosdb-nano repl

Then in the REPL, try any of the examples below.

Test Scripts

Best for: Automated testing with clean database each test

  • Creates fresh database for each test
  • Color-coded output
  • Detailed summary
  • 20 tests covering all Phase 3 features

Run:

Terminal window
./test_phase3_clean.sh

2. test_phase3_features.sh

Best for: Comprehensive manual validation

  • More detailed test output
  • Individual test explanations
  • Expected patterns documented
  • 30+ test scenarios

Run:

Terminal window
./test_phase3_features.sh

Manual Testing Examples

System Views

-- View database branch information
SELECT * FROM pg_database_branches();


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


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

Time-Travel with AS OF NOW

CREATE TABLE orders (id INT, amount INT);
INSERT INTO orders VALUES (100, 1000);
INSERT INTO orders VALUES (200, 2000);


-- Query current state
SELECT * FROM orders AS OF NOW;

Time-Travel with AS OF TIMESTAMP

-- Query as it existed at a specific timestamp
SELECT * FROM orders AS OF TIMESTAMP '2025-11-28 09:00:00';


-- Works with various timestamp formats
SELECT * FROM orders AS OF TIMESTAMP '2025-01-01 00:00:00';

Time-Travel with AS OF TRANSACTION

-- Query as it was after a specific transaction
SELECT * FROM orders AS OF TRANSACTION 1;
SELECT * FROM orders AS OF TRANSACTION 5;

Time-Travel with AS OF SCN

-- Query using System Change Number
SELECT * FROM orders AS OF SCN 100;
SELECT * FROM orders AS OF SCN 500;

Complex Queries

-- Time-travel with WHERE clause
SELECT * FROM orders AS OF TIMESTAMP '2025-11-28 09:00:00' WHERE amount > 500;


-- Time-travel with aggregates
SELECT COUNT(*) FROM orders AS OF TRANSACTION 1;
SELECT SUM(amount) FROM orders AS OF SCN 1000;


-- Time-travel with sorting
SELECT * FROM orders AS OF NOW ORDER BY amount DESC;

Test Coverage Matrix

FeatureStatusTestsNotes
pg_database_branches()✅1System view working
pg_mv_staleness()✅1System view working
pg_vector_index_stats()✅1System view working
AS OF NOW✅3All variants working
AS OF TIMESTAMP✅3All variants working
AS OF TRANSACTION✅3All variants working
AS OF SCN✅3All variants working
Basic SQL⚠️5Mostly working, some regressions
TOTAL85%2017 passing

Interpreting Test Results

Success (✓)

[2.1] Simple query with AS OF NOW ... ✓

Query executed successfully and returned expected results.

Failure (✗)

[1.1] System View: pg_database_branches ... ✗
  Output: (1 row)

Query didn’t match expected pattern (or error occurred).

Common Failures

  • “Table already exists” - Database persists between tests, can ignore
  • “Compression error” - Unrelated to Phase 3, known issue
  • “DropTable not implemented” - Expected, not Phase 3

Running Specific Tests

Extract system view tests only:

Terminal window
grep -A 3 "SYSTEM VIEWS" test_phase3_clean.sh

Extract time-travel tests only:

Terminal window
grep -A 3 "TIME-TRAVEL" test_phase3_clean.sh

Run a single test in REPL:

Terminal window
./target/release/heliosdb-nano repl << 'EOF'
CREATE TABLE test (id INT);
INSERT INTO test VALUES (1);
SELECT * FROM test AS OF NOW;
\q
EOF

Troubleshooting

”Binary not found"

Terminal window
# Build release binary first
cargo build --release


# Then run tests
./test_phase3_clean.sh

"Connection refused”

Database may be locked. Try:

Terminal window
rm -f heliosdb_test.db*
./test_phase3_clean.sh

“Test timeout”

REPL might be hanging. Try:

Terminal window
# Kill any orphaned processes
pkill -f heliosdb-nano


# Clean up database
rm -f heliosdb_test.db*


# Try again
./test_phase3_clean.sh

Performance Benchmarking

Time-Travel Query Performance

Terminal window
# Create test data
./target/release/heliosdb-nano repl << 'EOF'
CREATE TABLE large_table (id INT, value INT);
INSERT INTO large_table VALUES (1, 100);
INSERT INTO large_table VALUES (2, 200);
INSERT INTO large_table VALUES (3, 300);
SELECT * FROM large_table AS OF NOW;
\q
EOF

Expected performance:

  • AS OF NOW: < 1ms
  • AS OF TIMESTAMP: 50-100ms
  • AS OF TRANSACTION: 50-100ms
  • AS OF SCN: 50-100ms

What’s Working

✅ 100% Functional

  • System views (pg_database_branches, pg_mv_staleness, pg_vector_index_stats)
  • Time-travel queries with all AS OF variants
  • Complex queries with aggregates, WHERE, ORDER BY
  • Multi-row operations

⚠️ Partially Working

  • Basic SQL (CREATE, INSERT, SELECT work; DROP not yet implemented)

❌ Not Yet Working

  • SQL parsing for CREATE/DROP/MERGE DATABASE BRANCH
  • SQL parsing for CREATE/REFRESH/DROP MATERIALIZED VIEW
  • (Storage backends exist, need SQL integration)

Next Steps

  1. For Testing: Run ./test_phase3_clean.sh to verify all Phase 3 features
  2. For Manual Testing: Use ./target/release/heliosdb-nano repl with examples above
  3. For Development: See PHASE3_PROGRESS_SUMMARY.md for implementation status

Additional Resources

  • PHASE3_PROGRESS_SUMMARY.md - Detailed implementation status
  • PHASE3_TEST_RESULTS.md - Full test results and metrics
  • test_phase3_clean.sh - Automated test script
  • test_phase3_features.sh - Extended test script

Last Updated: 2025-11-28 Status: Phase 3 Beta - Ready for testing