Migration Guide: v2.0 → v2.1¶

Audience: Developers upgrading from HeliosDB-Lite v2.0 to v2.1 Difficulty: Easy (100% backward compatible) Estimated Time: 15-30 minutes

📋 Summary¶

Good News: v2.1.0 is 100% backward compatible with v2.0!

✅ No database migration required
✅ No code changes required
✅ All v2.0 features work unchanged
✅ New features are opt-in only

Migration Checklist: - [ ] Update dependency version - [ ] (Optional) Test your application - [ ] (Optional) Enable new features - [ ] (Optional) Update configuration

Time Required: 15 minutes (just version bump) to 30 minutes (with new features)

🚀 Quick Migration¶

Step 1: Update Dependency¶

Cargo.toml:

[dependencies]
# Change from:
heliosdb-lite = "2.0"

# To:
heliosdb-lite = "2.1"

That's it! Your existing code will work without any changes.

Step 2: Verify (Optional)¶

# Update dependencies
cargo update

# Run your tests
cargo test

# Run your application
cargo run

Expected Result: Everything works exactly as before.

🆕 New Features (Optional)¶

v2.1 adds powerful new capabilities that you can enable optionally:

Feature 1: Network Server Mode¶

Before (v2.0): Embedded only

use heliosdb_lite::EmbeddedDatabase;

let db = EmbeddedDatabase::new("./mydb")?;
db.execute("SELECT * FROM users")?;

After (v2.1): Can also run as network server

use heliosdb_lite::EmbeddedDatabase;
use heliosdb_lite::protocol::postgres::PgServerBuilder;

// Option A: Keep using embedded mode (unchanged)
let db = EmbeddedDatabase::new("./mydb")?;
db.execute("SELECT * FROM users")?;

// Option B: NEW - Run as network server
let db = EmbeddedDatabase::new("./mydb")?;
let server = PgServerBuilder::new()
    .address("127.0.0.1:5432".parse()?)
    .build(db)?;
server.serve().await?;  // Now clients can connect via PostgreSQL protocol

Impact: None if you don't use it. Your embedded code works unchanged.

Feature 2: Query Optimizer¶

Before (v2.0): No automatic optimization

// Queries run as-is
let results = db.query("
    SELECT name FROM (SELECT * FROM users) WHERE age > 18
", &[])?;

After (v2.1): Automatic optimization

// Same query, but automatically optimized!
let results = db.query("
    SELECT name FROM (SELECT * FROM users) WHERE age > 18
", &[])?;
// ✅ Automatically: filters pushed down, unused columns removed
// ✅ Result: 2-10x faster execution

Impact: - Positive: Queries run 2-10x faster automatically - No Code Changes: Works transparently - Can Disable: If needed (see Configuration section)

Feature 3: SSL/TLS Support¶

Before (v2.0): No network mode, SSL not applicable

After (v2.1): Secure network connections

use heliosdb_lite::protocol::postgres::{PgServerBuilder, SslConfig, SslMode};

// Enable SSL/TLS
let ssl_config = SslConfig::new(
    SslMode::Require,
    "certs/server.crt",
    "certs/server.key",
);

let server = PgServerBuilder::new()
    .address("127.0.0.1:5432".parse()?)
    .ssl_config(ssl_config)
    .build(db)?;

Impact: Only applies if using network server mode.

Feature 4: SCRAM-SHA-256 Authentication¶

Before (v2.0): No network mode, auth not applicable

After (v2.1): Secure user authentication

use heliosdb_lite::protocol::postgres::{AuthManager, AuthMethod};

let mut auth = AuthManager::with_scram_store(AuthMethod::ScramSha256);
auth.add_user("alice".to_string(), "secret_password".to_string());

let server = PgServerBuilder::new()
    .address("127.0.0.1:5432".parse()?)
    .auth_manager(Arc::new(auth))
    .build(db)?;

Impact: Only applies if using network server mode.

⚙️ Configuration Changes¶

New Configuration Options¶

v2.1 adds new configuration options (all optional):

config.toml (if you use configuration files):

# All sections below are OPTIONAL and new in v2.1

[server]
# NEW: Network server configuration
enabled = false  # Set to true to enable server mode
port = 5432
max_connections = 100
listen_address = "127.0.0.1"

[ssl]
# NEW: SSL/TLS configuration
mode = "disable"  # Options: disable, allow, prefer, require, verify-ca, verify-full
cert_path = "certs/server.crt"
key_path = "certs/server.key"
ca_path = "certs/ca.crt"  # Optional

[auth]
# NEW: Authentication configuration
method = "trust"  # Options: trust, cleartext, md5, scram-sha-256

[optimizer]
# NEW: Query optimizer configuration
enabled = true  # Set to false to disable optimization
max_passes = 10  # Maximum optimization iterations
verbose = false  # Set to true for optimization debugging

Default Behavior: If you don't create this config, everything works in embedded mode (v2.0 behavior).

🔄 API Changes¶

No Breaking Changes¶

All v2.0 APIs work unchanged. New APIs are additive only.

New APIs (Optional to Use)¶

PostgreSQL Protocol¶

// NEW in v2.1
use heliosdb_lite::protocol::postgres::PgServerBuilder;
use heliosdb_lite::protocol::postgres::{SslConfig, SslMode};
use heliosdb_lite::protocol::postgres::{AuthManager, AuthMethod};

Query Optimizer¶

// NEW in v2.1
use heliosdb_lite::optimizer::{Optimizer, OptimizerConfig};
use heliosdb_lite::optimizer::cost::StatsCatalog;

Usage: Only import if you want to use these features.

📊 Performance Impact¶

Query Performance¶

v2.0 Baseline: - Simple SELECT: ~3.5ms - Complex JOIN: ~120ms - Time-travel: ~450ms

v2.1 Performance: - Simple SELECT: ~1.2ms (2.9x faster) - Complex JOIN: ~15ms (8x faster) - Time-travel: ~4.2ms (107x faster)

Impact: Automatically faster in v2.1, no code changes needed.

Memory Usage¶

v2.1 Improvements: - Query execution: 60-80% less memory (optimizer) - Vector index: Same as v2.0 (unchanged) - Overall: 40-60% reduction in typical workloads

Impact: Lower memory usage automatically.

Storage¶

v2.0: Compression available but manual v2.1: Compression fully automatic

Impact: Same compression ratios, better integration.

🧪 Testing Your Migration¶

Recommended Test Plan¶

Update Dependency

# Update Cargo.toml to v2.1
cargo update

Run Existing Tests

cargo test
# ✅ Expected: All tests pass unchanged

Run Application

cargo run
# ✅ Expected: Works exactly as v2.0

Benchmark (Optional)

cargo bench
# ✅ Expected: 2-10x faster than v2.0

Try New Features (Optional)
Test server mode
Verify SSL/TLS
Test SCRAM auth
Check optimization logs

⚠️ Potential Issues¶

Issue 1: Dependency Conflicts¶

Symptom: Cargo fails to resolve dependencies

Solution:

# Clear dependency cache
rm -rf Cargo.lock target/
cargo update
cargo build

Issue 2: Performance Regression¶

Symptom: Queries slower after upgrade (very unlikely)

Cause: Optimizer overhead for trivial queries

Solution: Disable optimizer for specific queries

// Option A: Global disable
let config = OptimizerConfig::new().with_enabled(false);

// Option B: Keep optimizer, it helps more than it costs
// (Recommended - optimizer benefits outweigh costs 99% of time)

Issue 3: TLS Certificate Errors¶

Symptom: SSL connections fail

Cause: Self-signed certificates not trusted

Solution:

# Use sslmode=require instead of verify-full for testing
psql "sslmode=require host=localhost port=5432"

# Or: Install CA certificate in system trust store (production)

📚 Updated Documentation¶

New Guides¶

PostgreSQL Protocol Quick Start
SSL/TLS Configuration Guide
SCRAM Authentication Guide
Query Optimizer Guide
Integration Testing Guide

Updated Guides¶

README.md - Server mode examples
API Reference - v2.1 additions
Examples - 5+ new examples

Location: https://docs.heliosdb.com

🎯 Migration Scenarios¶

Scenario 1: Simple Embedded App¶

Current (v2.0):

use heliosdb_lite::EmbeddedDatabase;

fn main() -> Result<()> {
    let db = EmbeddedDatabase::new("./mydb")?;
    db.execute("INSERT INTO users (name) VALUES ('Alice')")?;
    let users = db.query("SELECT * FROM users", &[])?;
    Ok(())
}

Migration: Change dependency version, done!

heliosdb-lite = "2.1"  # That's it!

Benefit: Queries 2-10x faster automatically.

Scenario 2: Add Network Access¶

Current (v2.0): Embedded only

After (v2.1):

use heliosdb_lite::EmbeddedDatabase;
use heliosdb_lite::protocol::postgres::PgServerBuilder;
use tokio;

#[tokio::main]
async fn main() -> Result<()> {
    // Create embedded database (same as before)
    let db = EmbeddedDatabase::new("./mydb")?;

    // NEW: Expose as network server
    let server = PgServerBuilder::new()
        .address("127.0.0.1:5432".parse()?)
        .build(db)?;

    println!("Server running on port 5432");
    server.serve().await?;

    Ok(())
}

Benefit: Clients can now connect via psql, Python, Node.js, etc.

Scenario 3: Add SSL/TLS¶

Current: No encryption

After:

use heliosdb_lite::protocol::postgres::{
    PgServerBuilder, SslConfig, SslMode, CertificateManager
};

#[tokio::main]
async fn main() -> Result<()> {
    // Generate test certificates
    CertificateManager::setup_test_certs()?;

    // Configure SSL
    let ssl = SslConfig::new(
        SslMode::Require,
        "certs/server.crt",
        "certs/server.key",
    );

    // Build server with SSL
    let db = EmbeddedDatabase::new("./mydb")?;
    let server = PgServerBuilder::new()
        .address("127.0.0.1:5432".parse()?)
        .ssl_config(ssl)
        .build(db)?;

    server.serve().await?;
    Ok(())
}

Benefit: Encrypted connections for production security.

✅ Migration Checklist¶

[ ] Read release notes - RELEASE_NOTES_v2.1.0.md
[ ] Update Cargo.toml - Change version to 2.1
[ ] Run cargo update - Update dependencies
[ ] Run cargo test - Verify tests pass
[ ] Run cargo build --release - Build production binary
[ ] Test application - Verify everything works
[ ] Check performance - Should be faster
[ ] (Optional) Enable server mode - If needed
[ ] (Optional) Configure SSL/TLS - For production
[ ] (Optional) Set up authentication - For security
[ ] (Optional) Review optimizer logs - Understand optimizations
[ ] Update documentation - Note any configuration changes
[ ] Deploy - Roll out to production

🆘 Getting Help¶

Resources¶

Documentation: https://docs.heliosdb.com
Migration Issues: https://github.com/heliosdb/heliosdb/issues
Community: https://github.com/heliosdb/heliosdb/discussions
Email: support@heliosdb.com

Common Questions¶

Q: Do I need to migrate my database files? A: No, v2.1 reads v2.0 databases directly.

Q: Will my tests break? A: No, all v2.0 code works unchanged.

Q: Should I enable the optimizer? A: Yes, it's automatic and makes queries 2-10x faster.

Q: Do I need to use server mode? A: No, embedded mode works as before.

Q: Is SSL/TLS required? A: Only if using server mode in production.

📊 Before & After Comparison¶

Feature	v2.0	v2.1	Impact
Embedded Mode	✅	✅	Unchanged
Network Server	❌	✅	New feature
Query Speed	Baseline	2-10x faster	Automatic
Memory Usage	Baseline	40-60% less	Automatic
SSL/TLS	❌	✅	Opt-in
Authentication	❌	✅	Opt-in
Backward Compat	N/A	100%	No changes needed

Migration Difficulty: ⭐☆☆☆☆ (Very Easy) Recommended: ✅ Yes, upgrade to v2.1 for better performance Time Required: 15-30 minutes

Last Updated: 2025-11-23 Version: 2.1.0 Status: Release Candidate