---
title: "Advanced Feature Testing Guide"
---

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

```bash
cd HeliosDB-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:

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

## Feature Checks

### System Views

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

```sql
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:

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

### Database Branching

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

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

```bash
./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

```bash
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.