Skip to content
HeliosDB HeliosDB Full

Migration Guide: HeliosDB v2.0 → v3.0

Migration Guide: HeliosDB v2.0 → v3.0

Target Audience: Existing HeliosDB v2.0 users upgrading to v3.0 Estimated Migration Time: 30-60 minutes Downtime Required: Zero-downtime migration supported

Overview

HeliosDB v3.0 is fully backward compatible with v2.0. All existing applications will continue to work without code changes. This guide covers:

  1. Pre-migration checklist
  2. Step-by-step upgrade process
  3. New features to adopt
  4. Performance optimization tips
  5. Rollback procedures

Pre-Migration Checklist

1. Backup Your Data

Terminal window
# Full backup
heliosdb-cli backup --output /backups/v2_backup_$(date +%Y%m%d).tar.gz


# Verify backup integrity
heliosdb-cli verify-backup /backups/v2_backup_$(date +%Y%m%d).tar.gz

2. Review System Requirements

  • Rust: 1.70+ (unchanged)
  • Memory: 4GB minimum, 16GB recommended (unchanged)
  • Disk: 20% more for new indexes (if using new features)
  • OS: Linux, macOS, Windows (unchanged)

3. Check Dependencies

Terminal window
# Update dependencies
cargo update


# Verify compatibility
cargo check --all-features

Migration Steps

Step 1: Stop HeliosDB v2.0

Terminal window
# Graceful shutdown
heliosdb-cli shutdown --wait-for-checkpoints


# Verify clean shutdown
heliosdb-cli status

Step 2: Install HeliosDB v3.0

Terminal window
# Clone v3.0
git checkout v3.0-enterprise-features


# Build release binary
cargo build --release --all-features


# Verify installation
./target/release/heliosdb-cli --version
# Output: heliosdb 3.0.0

Step 3: Run Migration Script

Terminal window
# Automatic migration (handles schema upgrades)
heliosdb-cli migrate --from v2.0 --to v3.0


# Expected output:
# ✓ Detected v2.0 data directory
# ✓ Backing up metadata
# ✓ Upgrading storage format
# ✓ Building new indexes
# ✓ Verifying data integrity
# ✓ Migration complete (0 errors)

Step 4: Start HeliosDB v3.0

Terminal window
# Start with same configuration
heliosdb-server --config config.toml


# Verify startup
heliosdb-cli health-check
# Output: Status: Healthy, Version: 3.0.0

Step 5: Verify Data Integrity

Terminal window
# Run integrity checks
heliosdb-cli verify --full


# Compare row counts
heliosdb-cli query "SELECT table_name, COUNT(*) FROM information_schema.tables GROUP BY table_name"

What’s New in v3.0

New Features Available Immediately

1. Query Result Caching (Auto-Enabled)

-- Repeated queries automatically cached
SELECT * FROM users WHERE age > 25;
-- First run: 100ms, subsequent runs: <1ms


-- Configure cache
ALTER DATABASE SET query_cache_size = '2GB';
ALTER DATABASE SET query_cache_ttl = 300;  -- 5 minutes

2. Connection Pooling (Auto-Enabled)

// No code changes needed - automatically pooled
let conn = heliosdb::connect("heliosdb://localhost:5432").await?;

3. Enhanced MVCC (Auto-Enabled)

  • Read-only transactions now 2-3x faster
  • Better vacuum performance
  • No configuration needed

Adopting New Features

Enable Multi-Region Deployment

-- Add regions
CREATE REGION us_east DATACENTER 'aws-us-east-1';
CREATE REGION eu_west DATACENTER 'aws-eu-west-1';


-- Tables automatically replicated
INSERT INTO users VALUES (1, 'Alice', 'alice@example.com');
-- Replicated to all regions in <100ms

Enable Time-Series Optimizations

-- Configure retention
ALTER TABLE metrics SET timeseries_retention = '30 days';


-- Enable downsampling
ALTER TABLE metrics SET timeseries_downsample = (
    interval => '5 minutes',
    aggregation => 'avg'
);

Add Full-Text Search

-- Create full-text index
CREATE FULLTEXT INDEX fts_products ON products(name, description)
WITH LANGUAGE 'English';


-- Search
SELECT * FROM products WHERE MATCH(name, description) AGAINST('laptop');

Enable Row-Level Security

-- Create policy
CREATE POLICY user_data_isolation ON user_data
FOR SELECT
USING (user_id = current_user_id());


-- Enable RLS
ALTER TABLE user_data ENABLE ROW LEVEL SECURITY;

Add GraphQL API

Terminal window
# Enable GraphQL endpoint
heliosdb-cli graphql enable --port 8080


# Access GraphQL Playground
open http://localhost:8080/graphql

Performance Optimization

-- Enable automatic index recommendations
ALTER DATABASE SET adaptive_indexing = true;


-- Review recommendations
SELECT * FROM heliosdb_index_recommendations;


-- Apply recommended indexes
SELECT apply_index_recommendation(recommendation_id);

2. Read Replicas (For Read-Heavy Workloads)

-- Create read replica
CREATE READ REPLICA replica_1
WITH (
    async_lag_limit => '1 second',
    region => 'us_east'
);


-- Route read queries automatically
SET session_replication_role = 'replica';

3. Materialized Views (For Analytics)

-- Create materialized view
CREATE MATERIALIZED VIEW sales_summary AS
SELECT region, DATE(order_date), SUM(amount)
FROM sales
GROUP BY region, DATE(order_date);


-- Auto-refresh on commit
ALTER MATERIALIZED VIEW sales_summary SET REFRESH ON COMMIT;

4. Query Result Caching

-- Tune cache for your workload
ALTER DATABASE SET query_cache_size = '4GB';
ALTER DATABASE SET query_cache_ttl = 600;  -- 10 minutes
ALTER DATABASE SET query_cache_eviction = 'lru';

Breaking Changes

None. HeliosDB v3.0 is fully backward compatible with v2.0.

All v2.0 APIs, SQL syntax, and configurations continue to work unchanged.

Configuration Changes

New Configuration Options

config.toml
[query_cache]
enabled = true
size = "2GB"
ttl = 300
eviction_policy = "lru"


[adaptive_indexing]
enabled = true
recommendation_interval = "1h"
auto_apply = false


[multi_region]
enabled = false
regions = []
conflict_resolution = "last_write_wins"


[security]
row_level_security = true
data_masking = true
audit_logging = true
fips_mode = false


[performance]
connection_pool_size = 100
read_replicas = []
elastic_sharding = false

Deprecated Options (Still Work)

  • mvcc.vacuum_threshold → storage.vacuum_threshold
  • network.rdma_enabled → Removed (TCP/gRPC default)

Rollback Procedure

If you need to rollback to v2.0:

Step 1: Stop v3.0

Terminal window
heliosdb-cli shutdown --wait-for-checkpoints

Step 2: Restore v2.0 Backup

Terminal window
# Restore data
heliosdb-cli restore /backups/v2_backup_20251012.tar.gz


# Verify integrity
heliosdb-cli verify

Step 3: Start v2.0

Terminal window
git checkout v2.0
cargo build --release
./target/release/heliosdb-server --config config.toml

Step 4: Verify

Terminal window
heliosdb-cli health-check
# Output: Status: Healthy, Version: 2.0.0

Testing Recommendations

1. Staging Environment Test

Terminal window
# Clone production to staging
heliosdb-cli clone-db production staging


# Run migration on staging
heliosdb-cli migrate --from v2.0 --to v3.0 --database staging


# Run test suite
cargo test --all

2. Canary Deployment

Terminal window
# Deploy v3.0 to 10% of traffic
heliosdb-cli deploy --canary 10


# Monitor metrics
heliosdb-cli metrics --compare v2.0 v3.0


# Gradual rollout
heliosdb-cli deploy --canary 50
heliosdb-cli deploy --canary 100

3. Performance Comparison

Terminal window
# Run benchmark suite
heliosdb-bench --version v2.0 --output v2_baseline.json
heliosdb-bench --version v3.0 --output v3_results.json


# Compare results
heliosdb-bench compare v2_baseline.json v3_results.json

Post-Migration Tasks

1. Enable New Features Gradually

  • Week 1: Query caching, connection pooling (auto-enabled)
  • Week 2: Adaptive indexing recommendations
  • Week 3: Read replicas for read-heavy tables
  • Week 4: Materialized views for analytics
  • Month 2: Multi-region deployment (if needed)

2. Monitor Performance

-- Query cache hit rate
SELECT
    cache_hits,
    cache_misses,
    cache_hits::float / (cache_hits + cache_misses) as hit_rate
FROM heliosdb_cache_stats;


-- Index usage
SELECT * FROM heliosdb_index_usage ORDER BY scans DESC LIMIT 10;


-- Slow queries
SELECT * FROM heliosdb_slow_queries WHERE duration > 1000 ORDER BY duration DESC;

3. Update Applications

// Optional: Use new v3.0 features
use heliosdb::v3::{GraphQLClient, StreamingEngine, MlInference};


// GraphQL
let graphql = GraphQLClient::connect("http://localhost:8080/graphql").await?;
let users = graphql.query("{ users { id name } }").await?;


// Streaming analytics
let engine = StreamingEngine::new().await?;
let windowed = engine.tumbling_window(stream, Duration::from_secs(300)).await?;


// ML inference
let model = MlInference::load_onnx("fraud_model.onnx").await?;
let prediction = model.predict(&features).await?;

Support and Resources

Documentation

Community

Enterprise Support

Frequently Asked Questions

Q: Do I need to change my application code?

A: No. v3.0 is fully backward compatible. All v2.0 code works unchanged.

Q: How long does migration take?

A: 5-15 minutes for databases <100GB, 30-60 minutes for larger databases.

Q: Is there downtime?

A: Zero-downtime migration is supported using read replicas and canary deployment.

Q: Can I use v3.0 features with v2.0 clients?

A: Yes. v3.0 server supports v2.0 client protocol.

Q: What if migration fails?

A: Automatic rollback to v2.0 backup. No data loss.

Q: How do I verify data integrity?

A: Run heliosdb-cli verify --full after migration.

Success Checklist

  • Backup v2.0 data completed
  • v3.0 installed and verified
  • Migration script executed successfully
  • Data integrity verified
  • Performance benchmarks meet expectations
  • New features tested in staging
  • Monitoring and alerting configured
  • Team trained on new features
  • Rollback procedure documented and tested

Migration Complete! 🎉

Your HeliosDB instance is now running v3.0 with access to 30 enterprise features while maintaining full compatibility with existing applications.