Proposed Tutorials for HeliosDB Nano

Created: 2025-12-01 Target Version: v2.5.0

Overview

This document outlines proposed tutorials to achieve comprehensive documentation coverage. Each tutorial follows a consistent structure with hands-on examples.

Tutorial Template Structure

Each tutorial should include:

# [Feature] Tutorial

## Overview
- What the feature does
- Key benefits
- Use cases

## Prerequisites
- Required knowledge
- Required setup

## Concepts
- Core concepts explained
- Architecture diagrams

## Getting Started
- Basic setup
- First example

## Step-by-Step Guide
- Progressive complexity
- Working code examples

## Advanced Usage
- Power user features
- Integration patterns

## Best Practices
- Recommended patterns
- Performance tips

## Troubleshooting
- Common issues
- Solutions

## Reference
- API documentation links
- Related tutorials

1. Getting Started Tutorial

Priority: HIGH Estimated Length: 8-10 pages Target Audience: New users

Outline

# Getting Started with HeliosDB Nano

## Introduction
- What is HeliosDB Nano?
- Key features overview
- When to use HeliosDB Nano

## Installation
- Building from source
- Using pre-built binaries
- Docker setup

## Your First Database
- Creating a database
- Basic SQL operations
- Using the REPL

## Embedded vs Server Mode
- Embedded mode setup
- Server mode setup
- Choosing the right mode

## Quick Feature Tour
- Vector search preview
- Time-travel preview
- Branching preview

## Next Steps
- Recommended tutorials
- Community resources

Code Examples

// Embedded mode example
use heliosdb_nano::EmbeddedDatabase;

fn main() -> Result<(), Box<dyn std::error::Error>> {
    // Create database
    let db = EmbeddedDatabase::open("./my_database")?;

    // Create table
    db.execute("CREATE TABLE users (id INT, name TEXT, email TEXT)")?;

    // Insert data
    db.execute("INSERT INTO users VALUES (1, 'Alice', 'alice@example.com')")?;

    // Query data
    let results = db.query("SELECT * FROM users")?;
    for row in results {
        println!("{:?}", row);
    }

    Ok(())
}

2. Vector Search Tutorial

Priority: HIGH Estimated Length: 15-20 pages Target Audience: ML/AI developers

Outline

# Vector Search Tutorial

## Introduction
- What is vector search?
- Use cases (semantic search, recommendations, RAG)
- Vector databases vs traditional databases

## Vector Basics
- Understanding embeddings
- Dimension considerations
- Distance metrics (cosine, L2, dot product)

## Creating Vector Tables
- VECTOR data type
- Dimension specification
- Hybrid tables (vectors + traditional columns)

## Generating Embeddings
- Using OpenAI embeddings
- Using local models (sentence-transformers)
- Storing embeddings

## HNSW Indexing
- What is HNSW?
- Creating HNSW indexes
- Index parameters (m, ef_construction)
- Performance characteristics

## Similarity Search
- KNN queries
- Cosine similarity
- L2 distance
- Filtering with vectors

## Product Quantization
- Memory optimization
- Creating PQ indexes
- Accuracy vs memory tradeoff

## Real-World Examples
- Semantic document search
- Product recommendations
- Image similarity
- RAG pipeline integration

## Performance Tuning
- Index parameter optimization
- Batch operations
- Query optimization

## Monitoring
- pg_vector_index_stats
- Performance metrics

Code Examples

-- Create vector table
CREATE TABLE documents (
    id INT PRIMARY KEY,
    title TEXT,
    content TEXT,
    embedding VECTOR(384)
);

-- Insert with embedding
INSERT INTO documents VALUES (
    1,
    'Introduction to Machine Learning',
    'Machine learning is a subset of AI...',
    '[0.1, 0.2, 0.3, ...]'  -- 384-dimensional vector
);

-- Create HNSW index
CREATE INDEX idx_docs_embedding ON documents
USING hnsw (embedding)
WITH (m = 16, ef_construction = 200);

-- Semantic search
SELECT id, title, cosine_similarity(embedding, $query_embedding) as score
FROM documents
ORDER BY score DESC
LIMIT 10;

-- Hybrid search (vector + filter)
SELECT id, title, embedding <-> $query_embedding as distance
FROM documents
WHERE category = 'technology'
ORDER BY distance ASC
LIMIT 5;

3. Encryption Tutorial

Priority: HIGH Estimated Length: 10-15 pages Target Audience: Security-conscious developers

Outline

# Transparent Data Encryption (TDE) Tutorial

## Introduction
- What is TDE?
- Compliance requirements (HIPAA, GDPR, SOC2)
- Encryption at rest vs in transit

## Encryption Architecture
- AES-256-GCM
- Key derivation (Argon2)
- Encrypted storage layout

## Setting Up Encryption
- Generating encryption keys
- Configuring encryption
- Creating encrypted databases

## Key Management
- Key storage options
- Key rotation
- Key backup and recovery

## Working with Encrypted Data
- Transparent operations
- Performance considerations
- Debugging encrypted databases

## Security Best Practices
- Key management
- Access control
- Audit logging integration

## Compliance Scenarios
- HIPAA compliance setup
- GDPR data protection
- PCI-DSS requirements

## Recovery Scenarios
- Lost key recovery
- Database migration
- Backup and restore

Code Examples

use heliosdb_nano::{EmbeddedDatabase, Config};

// Create encrypted database
let config = Config {
    encryption_key: Some("your-32-byte-encryption-key-here".to_string()),
    key_derivation: KeyDerivation::Argon2 {
        memory_cost: 65536,
        time_cost: 3,
        parallelism: 4,
    },
    ..Default::default()
};

let db = EmbeddedDatabase::open_with_config("./encrypted_db", config)?;

// All operations are transparently encrypted
db.execute("CREATE TABLE secrets (id INT, data TEXT)")?;
db.execute("INSERT INTO secrets VALUES (1, 'sensitive information')")?;

// Key rotation
db.rotate_encryption_key("new-32-byte-encryption-key-here")?;

4. Materialized Views Tutorial

Priority: HIGH Estimated Length: 15-20 pages Target Audience: Analytics developers

Outline

# Materialized Views Tutorial

## Introduction
- What are materialized views?
- Views vs Materialized Views
- Use cases (dashboards, reports, caching)

## Basic Materialized Views
- Creating materialized views
- Querying materialized views
- Manual refresh

## Auto-Refresh
- Configuring auto-refresh
- Refresh intervals
- CPU-aware scheduling

## Incremental Refresh
- How incremental refresh works
- Delta tracking
- Performance benefits

## Advanced Patterns
- Cascading MVs
- MVs with aggregations
- MVs with joins

## Monitoring
- pg_mv_staleness view
- Refresh history
- Performance metrics

## Best Practices
- When to use MVs
- Refresh strategy
- Index optimization

## Real-World Examples
- Dashboard metrics
- Report generation
- API response caching

Code Examples

-- Basic materialized view
CREATE MATERIALIZED VIEW sales_summary AS
SELECT
    DATE(created_at) as sale_date,
    product_id,
    SUM(quantity) as total_quantity,
    SUM(amount) as total_revenue
FROM sales
GROUP BY DATE(created_at), product_id;

-- Auto-refresh MV
CREATE MATERIALIZED VIEW hourly_metrics
WITH (
    auto_refresh = true,
    refresh_interval = '1 hour',
    cpu_threshold = 70
)
AS SELECT
    DATE_TRUNC('hour', timestamp) as hour,
    COUNT(*) as event_count,
    AVG(duration) as avg_duration
FROM events
GROUP BY DATE_TRUNC('hour', timestamp);

-- Incremental refresh MV
CREATE MATERIALIZED VIEW customer_lifetime_value
WITH (incremental = true)
AS SELECT
    customer_id,
    COUNT(DISTINCT order_id) as total_orders,
    SUM(amount) as lifetime_value,
    MAX(order_date) as last_order
FROM orders
GROUP BY customer_id;

-- Monitor staleness
SELECT * FROM pg_mv_staleness()
WHERE staleness_seconds > 3600;

-- Manual refresh
REFRESH MATERIALIZED VIEW sales_summary;
REFRESH MATERIALIZED VIEW CONCURRENTLY hourly_metrics;

5. REST API Tutorial

Priority: HIGH Estimated Length: 10-15 pages Target Audience: API developers

Outline

# REST API Tutorial

## Introduction
- API Overview
- Authentication options
- Base URL configuration

## Setup
- Starting the API server
- Configuration options
- SSL/TLS setup

## Branch Operations
- Listing branches
- Creating branches
- Deleting branches
- Merging branches

## Data Operations
- Querying data
- Inserting data
- Updating data
- Deleting data

## SQL Execution
- Running queries
- DDL operations
- Parameterized queries

## Time-Travel via API
- AS OF queries
- Historical data access
- Snapshot management

## Error Handling
- Error codes
- Retry strategies
- Rate limiting

## SDK Usage
- Rust client
- JavaScript/TypeScript client
- Python client

## Security
- JWT authentication
- API key management
- Request signing

Code Examples

# List branches
curl -X GET "http://localhost:8080/v1/branches" \
    -H "Authorization: Bearer $TOKEN"

# Create branch
curl -X POST "http://localhost:8080/v1/branches" \
    -H "Authorization: Bearer $TOKEN" \
    -H "Content-Type: application/json" \
    -d '{
        "name": "feature-branch",
        "source_branch": "main",
        "as_of": {"type": "now"}
    }'

# Execute query
curl -X POST "http://localhost:8080/v1/branches/main/query" \
    -H "Authorization: Bearer $TOKEN" \
    -H "Content-Type: application/json" \
    -d '{
        "sql": "SELECT * FROM users WHERE active = true",
        "as_of": {"type": "timestamp", "value": "2025-12-01T10:00:00Z"}
    }'

# Merge branches
curl -X POST "http://localhost:8080/v1/branches/feature-branch/merge" \
    -H "Authorization: Bearer $TOKEN" \
    -H "Content-Type: application/json" \
    -d '{
        "target_branch": "main",
        "conflict_resolution": "source_wins",
        "delete_source_after_merge": true
    }'

6. Audit Logging Tutorial

Priority: MEDIUM Estimated Length: 8-12 pages Target Audience: Compliance teams

Outline

# Audit Logging Tutorial

## Introduction
- What is audit logging?
- Compliance requirements
- Audit trail importance

## Configuration
- Enabling audit logging
- Log destinations
- Log format options

## Event Types
- DDL events
- DML events
- Security events
- Query events

## Querying Audit Logs
- heliosdb_audit_log table
- Filtering by event type
- Time-based queries

## Log Management
- Log rotation
- Archival strategies
- Retention policies

## Compliance Scenarios
- SOC2 audit trails
- HIPAA access logging
- GDPR data access

## Integration
- SIEM integration
- Log forwarding
- Alert configuration

## Tamper Detection
- Hash verification
- Chain of custody
- Forensic analysis

7. Query Optimization Tutorial

Priority: MEDIUM Estimated Length: 12-18 pages Target Audience: Performance engineers

Outline

# Query Optimization Tutorial

## Introduction
- Query execution pipeline
- Cost-based optimization
- Query plan analysis

## EXPLAIN Command
- Basic EXPLAIN
- EXPLAIN ANALYZE
- Visual query plans

## Index Optimization
- B-tree indexes
- HNSW indexes
- Index selection

## Index Recommender
- Automatic recommendations
- Analyzing recommendations
- Implementing suggestions

## Query Patterns
- Join optimization
- Subquery optimization
- Aggregate optimization

## Statistics
- Table statistics
- Column statistics
- Statistics updates

## Performance Tuning
- Memory configuration
- Parallelism settings
- Cache optimization

## Monitoring
- Slow query log
- Performance metrics
- Bottleneck identification

8. Multi-Tenancy Tutorial

Priority: MEDIUM Estimated Length: 10-15 pages Target Audience: SaaS developers

Outline

# Multi-Tenancy Tutorial

## Introduction
- Multi-tenancy patterns
- Isolation requirements
- HeliosDB Nano approach

## Row-Level Security
- Policy definition
- Tenant context
- Query filtering

## Schema Isolation
- Schema per tenant
- Cross-tenant queries
- Migration patterns

## Performance Considerations
- Index strategies
- Query optimization
- Resource allocation

## Security
- Tenant isolation verification
- Access control
- Audit logging per tenant

## Scaling
- Tenant partitioning
- Load balancing
- Capacity planning

## Operations
- Tenant provisioning
- Data migration
- Backup per tenant

Tutorial Development Schedule

Tutorial	Priority	Week	Owner
Getting Started	HIGH	7	Docs
Vector Search	HIGH	7	Docs
Encryption	HIGH	7	Docs
REST API	HIGH	7	Docs
Materialized Views	HIGH	8	Docs
Audit Logging	MEDIUM	8	Docs
Query Optimization	MEDIUM	9	Docs
Multi-Tenancy	MEDIUM	9	Docs
REPL Tutorial	LOW	10	Docs
PostgreSQL Protocol	LOW	10	Docs

Tutorial Quality Checklist

Each tutorial must:

Include working code examples
Be tested against latest release
Include screenshots where applicable
Have consistent formatting
Link to related documentation
Include troubleshooting section
Be reviewed by domain expert
Pass technical accuracy review

Feedback Collection

Each tutorial should include:

---

## Feedback

Was this tutorial helpful? Let us know!

- [Report an issue](https://github.com/heliosdb/heliosdb/issues/new?labels=documentation)
- [Suggest improvements](https://github.com/heliosdb/heliosdb/discussions)
- [Ask questions](https://github.com/heliosdb/heliosdb/discussions/categories/q-a)

Document Version: 1.0 Last Updated: 2025-12-01