Advanced Feature Testing Guide

Quick reference for validating HeliosDB Nano branching, time-travel, materialized view, vector index, and PostgreSQL protocol behavior.

Quick Start

Run focused Cargo tests from the Nano source tree:

cd ~/Helios/Nano
cargo test branch_sql_integration_tests
cargo test materialized_view_tests
cargo test repl_meta_commands
cargo test time_travel_system_views_tests

Use the REPL for manual checks:

./target/release/heliosdb-nano repl

Feature Checks

System Views

SELECT * FROM pg_database_branches();
SELECT * FROM pg_mv_staleness();
SELECT * FROM pg_vector_index_stats();

pg_database_branches() includes the main branch on a new database. Materialized view and vector index views populate after creating the corresponding objects.

Time-Travel Queries

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

SELECT * FROM orders AS OF NOW;
SELECT * FROM orders AS OF TIMESTAMP '2025-11-28 09:00:00';
SELECT * FROM orders AS OF TRANSACTION 1;
SELECT * FROM orders AS OF SCN 100;

Time-travel queries can be combined with filters, aggregates, and ordering:

SELECT COUNT(*) FROM orders AS OF TRANSACTION 1;
SELECT * FROM orders AS OF NOW WHERE amount > 500 ORDER BY amount DESC;

Database Branching

CREATE DATABASE BRANCH dev FROM main AS OF NOW;
SELECT branch_name, status FROM pg_database_branches();
MERGE DATABASE BRANCH dev INTO main;
DROP DATABASE BRANCH IF EXISTS dev;

Materialized Views

CREATE TABLE sales (region TEXT, amount INT);
INSERT INTO sales VALUES ('west', 100), ('west', 200), ('east', 80);

CREATE MATERIALIZED VIEW sales_by_region AS
SELECT region, SUM(amount) AS total
FROM sales
GROUP BY region;

SELECT * FROM sales_by_region;
REFRESH MATERIALIZED VIEW sales_by_region;
SELECT * FROM pg_mv_staleness();

Cargo Test Targets

Area	Command
Branch SQL	`cargo test branch_sql_integration_tests`
Materialized views	`cargo test materialized_view_tests`
Materialized view integration	`cargo test materialized_view_integration`
REPL system views	`cargo test repl_meta_commands`
Time-travel with system views	`cargo test time_travel_system_views_tests`
PostgreSQL SCRAM auth	`cargo test --test postgres_scram_auth_tests`
PostgreSQL SSL/TLS	`cargo test --test postgres_ssl_tests`
PostgreSQL extended protocol	`cargo test --test postgres_extended_protocol_tests`
Binary int4 protocol regression	`cargo test --test v334_a15_binary_int4`

Manual REPL Smoke Test

./target/release/heliosdb-nano repl << 'EOF'
CREATE TABLE test (id INT, name TEXT);
INSERT INTO test VALUES (1, 'Hello');
SELECT * FROM test AS OF NOW;
CREATE DATABASE BRANCH smoke FROM main AS OF NOW;
SELECT branch_name FROM pg_database_branches();
DROP DATABASE BRANCH smoke;
\q
EOF

Troubleshooting

Binary Not Found

cargo build --release

Database Lock

Use a fresh database path for the smoke test or stop the process that owns the current database.

Protocol Tests Rebuild RocksDB

The PostgreSQL protocol tests can trigger a RocksDB rebuild on a cold target directory. If the build fails before Rust tests start, clean the interrupted build output and rerun the focused target.