HeliosDB Nano REPL Demo

This document demonstrates an interactive REPL session with HeliosDB Nano.

Starting the REPL

$ heliosdb-nano repl --memory

HeliosDB Nano v3.7.0
PostgreSQL-compatible embedded database

Type \h for help, \q to quit

heliosdb>

Demo Session

1. Show Help

heliosdb> \h

HeliosDB Nano REPL Commands
════════════════════════════════════════════════════════════

Meta Commands:
  \q, \quit, \exit  - Quit the REPL
  \h, \help, \?        - Show this help
  \d                - List all tables
  \d <table>          - Describe table schema
  \dt               - List tables with details
  \timing           - Toggle query timing
  \e, \edit          - Edit query in $EDITOR (not yet implemented)

SQL Commands:
  End SQL statements with semicolon (;)
  Multi-line statements are supported
  Press Ctrl-C to cancel current input
  Press Ctrl-D to exit

Examples:
  CREATE TABLE users (id INT, name TEXT);
  INSERT INTO users VALUES (1, 'Alice');
  SELECT * FROM users;
  \d users

heliosdb>

2. Create Tables

heliosdb> CREATE TABLE users (
       ->   id INT PRIMARY KEY,
       ->   name TEXT NOT NULL,
       ->   email TEXT,
       ->   created_at TIMESTAMP
       -> );
Query OK (0.002s)

heliosdb> CREATE TABLE orders (
       ->   id INT PRIMARY KEY,
       ->   user_id INT,
       ->   amount FLOAT8,
       ->   status TEXT
       -> );
Query OK (0.001s)

heliosdb> \d

Tables:
  orders
  users

3. Describe Table Schema

heliosdb> \d users

Table: users
──────────────────────────────────────────────────
Column               Type            Nullable   Primary Key
──────────────────────────────────────────────────
id                   Int4            NO         YES
name                 Text            NO
email                Text            YES
created_at           Timestamp       YES

4. Insert Data

heliosdb> INSERT INTO users (id, name, email)
       -> VALUES (1, 'Alice Smith', 'alice@example.com'),
       ->        (2, 'Bob Johnson', 'bob@example.com'),
       ->        (3, 'Charlie Brown', 'charlie@example.com');
Query OK, 3 rows affected (0.001s)

heliosdb> INSERT INTO orders (id, user_id, amount, status)
       -> VALUES (101, 1, 150.00, 'completed'),
       ->        (102, 1, 75.50, 'pending'),
       ->        (103, 2, 200.00, 'completed'),
       ->        (104, 3, 99.99, 'shipped');
Query OK, 4 rows affected (0.001s)

5. Query Data

heliosdb> SELECT * FROM users;
┌────┬────────────────┬────────────────────────┬────────────┐
│ id │ name           │ email                  │ created_at │
├────┼────────────────┼────────────────────────┼────────────┤
│ 1  │ Alice Smith    │ alice@example.com      │ NULL       │
│ 2  │ Bob Johnson    │ bob@example.com        │ NULL       │
│ 3  │ Charlie Brown  │ charlie@example.com    │ NULL       │
└────┴────────────────┴────────────────────────┴────────────┘
(3 rows) (0.001s)

heliosdb> SELECT * FROM orders WHERE status = 'completed';
┌─────┬─────────┬────────┬───────────┐
│ id  │ user_id │ amount │ status    │
├─────┼─────────┼────────┼───────────┤
│ 101 │ 1       │ 150.00 │ completed │
│ 103 │ 2       │ 200.00 │ completed │
└─────┴─────────┴────────┴───────────┘
(2 rows) (0.002s)

6. Aggregate Queries

heliosdb> SELECT
       ->   status,
       ->   COUNT(*) as order_count,
       ->   SUM(amount) as total_amount,
       ->   AVG(amount) as avg_amount
       -> FROM orders
       -> GROUP BY status;
┌───────────┬─────────────┬──────────────┬────────────┐
│ status    │ order_count │ total_amount │ avg_amount │
├───────────┼─────────────┼──────────────┼────────────┤
│ completed │ 2           │ 350.00       │ 175.00     │
│ pending   │ 1           │ 75.50        │ 75.50      │
│ shipped   │ 1           │ 99.99        │ 99.99      │
└───────────┴─────────────┴──────────────┴────────────┘
(3 rows) (0.003s)

7. Update Data

heliosdb> UPDATE orders SET status = 'completed' WHERE id = 102;
Query OK, 1 row affected (0.001s)

heliosdb> SELECT * FROM orders WHERE user_id = 1;
┌─────┬─────────┬────────┬───────────┐
│ id  │ user_id │ amount │ status    │
├─────┼─────────┼────────┼───────────┤
│ 101 │ 1       │ 150.00 │ completed │
│ 102 │ 1       │ 75.50  │ completed │
└─────┴─────────┴────────┴───────────┘
(2 rows) (0.001s)

8. Delete Data

heliosdb> DELETE FROM orders WHERE status = 'shipped';
Query OK, 1 row affected (0.001s)

heliosdb> SELECT COUNT(*) as remaining_orders FROM orders;
┌──────────────────┐
│ remaining_orders │
├──────────────────┤
│ 3                │
└──────────────────┘
(1 row) (0.001s)

9. Join Query

heliosdb> SELECT u.name, COUNT(o.id) as order_count, SUM(o.amount) as total_spent
       -> FROM users u
       -> LEFT JOIN orders o ON u.id = o.user_id
       -> GROUP BY u.name;
┌────────────────┬─────────────┬─────────────┐
│ name           │ order_count │ total_spent │
├────────────────┼─────────────┼─────────────┤
│ Alice Smith    │ 2           │ 225.50      │
│ Bob Johnson    │ 1           │ 200.00      │
│ Charlie Brown  │ 0           │ NULL        │
└────────────────┴─────────────┴─────────────┘
(3 rows) (0.004s)

10. Toggle Timing

heliosdb> \timing
Timing is off

heliosdb> SELECT * FROM users LIMIT 1;
┌────┬──────────────┬───────────────────┬────────────┐
│ id │ name         │ email             │ created_at │
├────┼──────────────┼───────────────────┼────────────┤
│ 1  │ Alice Smith  │ alice@example.com │ NULL       │
└────┴──────────────┴───────────────────┴────────────┘
(1 row)

heliosdb> \timing
Timing is on

11. List All Tables

heliosdb> \dt

Tables:
────────────────────────────────────────────────────────────
Name                           Columns
────────────────────────────────────────────────────────────
orders                         4
users                          4

12. Exit

heliosdb> \q
Goodbye!

Advanced Features

Auto-Completion Demo

heliosdb> SEL<TAB>
→ SELECT

heliosdb> SELECT * FROM us<TAB>
→ SELECT * FROM users

heliosdb> SELECT na<TAB>
→ SELECT name

Multi-Line Cancel

heliosdb> SELECT * FROM users
       -> WHERE id = 1
       -> AND name LIKE 'A%'
       -> ^C
heliosdb>

Use ↑ and ↓ to navigate previous commands Use Ctrl-R for reverse search

Error Handling

heliosdb> SELECT * FROM nonexistent_table;
ERROR: Table 'nonexistent_table' does not exist

heliosdb> INSERT INTO users (invalid_column) VALUES (1);
ERROR: Column 'invalid_column' does not exist

Running with Persistent Storage

# Create a database directory
$ mkdir mydb

# Start REPL with persistent storage
$ heliosdb-nano repl -d mydb

HeliosDB Nano v3.7.0
PostgreSQL-compatible embedded database

Type \h for help, \q to quit

heliosdb> CREATE TABLE persistent_data (id INT, value TEXT);
Query OK (0.002s)

heliosdb> INSERT INTO persistent_data VALUES (1, 'This data persists!');
Query OK, 1 row affected (0.001s)

heliosdb> \q
Goodbye!

# Restart REPL - data is still there!
$ heliosdb-nano repl -d mydb

heliosdb> SELECT * FROM persistent_data;
┌────┬──────────────────────┐
│ id │ value                │
├────┼──────────────────────┤
│ 1  │ This data persists!  │
└────┴──────────────────────┘
(1 row) (0.001s)

Tips for Effective REPL Usage

Use \d commands frequently to understand your schema
Format multi-line queries for better readability
Keep timing on during development to identify slow queries
Leverage history with ↑/↓ to avoid retyping
Use auto-completion (Tab) to speed up typing
Test in —memory mode for quick experiments
Use persistent mode for development databases

Performance Example

heliosdb> \timing
Timing is on

heliosdb> CREATE TABLE large_table (id INT, data TEXT);
Query OK (0.002s)

heliosdb> -- Batch insert (simulated)
heliosdb> INSERT INTO large_table
       -> SELECT generate_series(1, 1000), 'test data';
Query OK, 1000 rows affected (0.125s)

heliosdb> SELECT COUNT(*) FROM large_table;
┌───────┐
│ count │
├───────┤
│ 1000  │
└───────┘
(1 row) (0.003s)

Conclusion

The HeliosDB Nano REPL provides a powerful, user-friendly interface for:

Interactive database development
Quick data exploration
Testing SQL queries
Learning SQL and database concepts
Prototyping applications

For more information, see:

REPL Guide - Complete REPL documentation
SQL Reference - SQL syntax guide
User Guide - Getting started guide

HeliosDB Nano REPL Demo

HeliosDB Nano REPL Demo

Starting the REPL

Demo Session

1. Show Help

2. Create Tables

3. Describe Table Schema

4. Insert Data

5. Query Data

6. Aggregate Queries

7. Update Data

8. Delete Data

9. Join Query

10. Toggle Timing

11. List All Tables

12. Exit

Advanced Features

Auto-Completion Demo

Multi-Line Cancel

History Navigation

Error Handling

Running with Persistent Storage

Tips for Effective REPL Usage

Performance Example

Conclusion