HeliosDB v4.0 User Guides

Complete tutorial-style guides for all 12 breakthrough features in HeliosDB v4.0.

Overview

HeliosDB v4.0 introduces 12 innovative features that bring serverless scalability, advanced storage optimization, and enterprise-grade distributed database capabilities. This collection provides comprehensive, beginner-friendly guides with step-by-step instructions, SQL examples, troubleshooting tips, and best practices.

Feature Categories

Serverless & Scaling (Tier 1)

Core Innovation: Scale from 0 to maximum compute instantly while only paying for what you use.

Git-Style Database Branching
- Instant zero-copy database branches
- Time-travel queries
- Development/testing isolation
- Branch creation: <1ms, zero storage overhead
Scale-to-Zero Serverless Compute
- Automatic suspend/resume
- Sub-300ms resume time
- 50-90% cost savings
- Transparent to applications
Dynamic Autoscaling (0-to-Max CU)
- Real-time resource adjustment
- Sub-10s scale-up, sub-60s scale-down
- Intelligent damping (no oscillation)
- 28%+ cost optimization

Distribution & High Availability (Tier 1)

Core Innovation: Query any node, automatic routing, and intelligent rebalancing.

Query from Any Node
- Connect to any cluster node
- Automatic query routing
- Load balancing
- No single point of failure
Smart Data Rebalancing
- Automatic load balancing
- Zero-downtime redistribution
- Bandwidth throttling
- Capacity and access-based strategies

Advanced Storage (Tier 2)

Core Innovation: Intelligent multi-tier storage and compression.

Hybrid Columnar Compression (HCC)
- 3-10x compression ratios
- Oracle Exadata-style compression
- Multiple algorithms (ZSTD, LZ4, Snappy)
- Configurable per table/column

Sharding & Multi-Tenancy (Tier 2)

Core Innovation: Advanced sharding with tenant isolation.

Schema-Based Sharding
- Shard by schema/tenant
- Perfect data isolation
- Independent scaling per tenant
- Compliance-friendly
Distributed Foreign Keys
- Cross-shard referential integrity
- 2PC for ACID guarantees
- Transparent FK validation
- Multiple validation modes

Storage Optimization (Tier 3)

Core Innovation: Cost-optimized multi-tier storage.

3-Tier Storage (Hot/Warm/Cold)
- NVMe (hot) / SATA (warm) / S3 (cold)
- 80%+ cost reduction for 100TB+ databases
- Automatic tiering policies
- Sub-ms to 50ms latency tiers
Safekeeper WAL Service
- Dedicated fault-tolerant WAL storage
- Instant compute recovery
- Compute-storage separation
- 3+ replica durability

Online Operations (Tier 3)

Core Innovation: Zero-downtime schema and infrastructure changes.

Online Schema & Shard Changes
- Zero-downtime shard key changes
- Online shard splits
- No application modifications
- Automatic migration and validation
Tenant Resource Quotas
- Per-tenant CPU/memory/storage limits
- QoS tiers (bronze/silver/gold)
- Fair resource allocation
- Usage tracking and billing

Quick Start

Choose Your Path

For Developers:

Start with Branching - Create isolated dev environments
Then Autoscaling - Optimize dev/staging costs
Finally Tiered Storage - Reduce storage costs

For DBAs:

Start with Query Routing - Understand distributed architecture
Then Rebalancing - Maintain cluster health
Finally Online Sharding - Scale without downtime

For SaaS Builders:

Start with Schema Sharding - Tenant isolation
Then Resource Quotas - Fair resource allocation
Finally Distributed FK - Cross-tenant integrity

For Cost Optimization:

Start with Scale-to-Zero - Eliminate idle costs
Then Tiered Storage - 80% storage savings
Finally Autoscaling - Dynamic right-sizing

Feature Matrix

Feature	Complexity	Setup Time	Cost Impact	Production Ready
Branching	Low	5 min	0-10% storage	Yes
Scale-to-Zero	Medium	15 min	50-90% savings	Yes
Autoscaling	Medium	20 min	28%+ savings	Yes
Query Routing	Low	10 min	Neutral	Yes
Rebalancing	Low	10 min	Neutral	Yes
Compression	Low	5 min	3-10x storage	Yes
Schema Sharding	Medium	30 min	Neutral	Yes
Distributed FK	High	45 min	Slight overhead	Yes
Tiered Storage	High	1 hour	80%+ savings	Yes
Safekeeper	Medium	30 min	Slight increase	Yes
Online Sharding	High	1 hour	Neutral	Yes
Quotas	Medium	20 min	Revenue protection	Yes

Common Workflows

Development Environment Setup

# 1. Enable branching for feature isolation
heliosdb-cli config set branching.enabled=true

# 2. Enable autoscaling with scale-to-zero
heliosdb-cli config set autoscaling.min_cu=0.0

# 3. Create dev branch
heliosdb-cli branch create dev/feature-auth

# 4. Work in isolation, auto-suspends after 5min idle
# Cost: Near zero when not actively developing

Production Multi-Tenant SaaS

# 1. Enable schema-based sharding
heliosdb-cli config set sharding.strategy=schema_based

# 2. Configure resource quotas
heliosdb-cli quota create gold_tier cpu=50 memory=16GB

# 3. Enable distributed FK for referential integrity
heliosdb-cli config set distributed_fk.enabled=true

# 4. Set up tiered storage for cost optimization
heliosdb-cli tier configure hot=1TB warm=5TB cold=s3://bucket

Large-Scale Analytics

# 1. Enable tiered storage (archive old data to S3)
heliosdb-cli tier configure \
    hot=2TB,7days \
    warm=10TB,30days \
    cold=s3://analytics-archive

# 2. Enable HCC compression
heliosdb-cli config set compression.default=zstd

# 3. Configure autoscaling for query workload
heliosdb-cli autoscale configure \
    min=2.0 max=32.0 target_cpu=75

# Result: 80% storage savings + dynamic compute scaling

Performance Targets

Achieved in v4.0

Metric	Target	Achieved	Status
Branch creation	<100ms	<1ms	100x faster
Resume time	<300ms	~170ms	43% faster
Scale-up time	<10s	<2s	5x faster
Storage savings	80%	85%	Exceeded
Cost reduction	28%	28%+	Met

Troubleshooting

Common Issues

Feature Not Available:

-- Check HeliosDB version
SELECT version();  -- Must be v3.2+

-- Check feature enablement
SELECT * FROM heliosdb.features WHERE enabled = true;

Performance Issues:

-- Check resource utilization
SELECT * FROM heliosdb.resource_usage;

-- Check autoscaling status
SELECT * FROM heliosdb.autoscale_status;

-- Check tier performance
SELECT * FROM heliosdb.tier_performance;

Configuration Problems:

# Validate configuration
heliosdb-cli config validate

# Check logs
tail -f /var/log/heliosdb/heliosdb.log

# Test connectivity
heliosdb-cli cluster status

Best Practices Summary

General Guidelines

Start Conservative: Begin with default settings, tune based on metrics
Monitor First: Observe for 1 week before optimization
Test in Staging: Always validate changes in non-production first
Document Changes: Keep track of configuration modifications
Set Alerts: Configure Prometheus/Grafana alerts for critical metrics

Security Considerations

-- Restrict branch creation to admins
REVOKE EXECUTE ON FUNCTION heliosdb.create_branch FROM public;
GRANT EXECUTE ON FUNCTION heliosdb.create_branch TO admin_role;

-- Audit all configuration changes
CREATE TABLE config_audit (
    timestamp TIMESTAMPTZ DEFAULT now(),
    user_name TEXT,
    parameter TEXT,
    old_value TEXT,
    new_value TEXT
);

Cost Optimization Checklist

Enable scale-to-zero for dev/staging
Configure autoscaling for production
Set up tiered storage (hot/warm/cold)
Enable HCC compression
Monitor CU-hour consumption
Review resource quotas monthly
Clean up old branches regularly

Integration Examples

With Kubernetes

apiVersion: v1
kind: ConfigMap
metadata:
  name: heliosdb-config
data:
  heliosdb.yaml: |
    autoscaling:
      enabled: true
      min_cu: 0.0
      max_cu: 16.0
    tiered_storage:
      enabled: true
      cold_tier:
        type: s3
        bucket: ${S3_BUCKET}

With Terraform

resource "heliosdb_cluster" "main" {
  name = "production"

  autoscaling {
    enabled = true
    min_cu  = 2.0
    max_cu  = 32.0
  }

  tiered_storage {
    hot_size_gb  = 1000
    warm_size_gb = 5000
    cold_bucket  = aws_s3_bucket.cold_tier.id
  }
}

With Prometheus

scrape_configs:
  - job_name: 'heliosdb'
    static_configs:
      - targets: ['heliosdb:9090']
    metrics_path: '/metrics'
    scrape_interval: 15s

Monitoring Dashboard

Key Metrics to Track

Autoscaling:

Current CU level
CPU/memory utilization
Scaling events frequency
Cost per hour

Tiered Storage:

Per-tier usage
Migration rate
Cold tier latency
Cost savings

Branching:

Active branch count
Branch storage overhead
Branch age distribution

Cluster Health:

Node availability
Rebalancing status
Query routing latency
Resource quota utilization

Additional Resources

Documentation

Community

GitHub: https://github.com/heliosdb/heliosdb
Discord: https://discord.gg/heliosdb
Forum: https://community.heliosdb.com
Stack Overflow: Tag heliosdb

Support

Community Support: GitHub Issues
Enterprise Support: enterprise@heliosdb.com
Documentation: https://docs.heliosdb.com
Training: https://learn.heliosdb.com

Release Information

Version: 4.0.0 Release Date: October 2025 Status: Production Ready License: Apache-2.0

What’s Next

v4.1 (Q1 2026):

Enhanced ML-based autoscaling
Cross-region tiered storage
Advanced quota policies
Improved compression algorithms

v4.2 (Q2 2026):

Multi-cluster branching
Predictive scaling
Tiered compute (hot/warm/cold compute nodes)
Enhanced observability

Feedback

We value your feedback! Please report issues, suggest improvements, or share success stories:

Bug Reports: GitHub Issues
Feature Requests: GitHub Discussions
Success Stories: community@heliosdb.com

HeliosDB v4.0 User Guides

Complete guide collection for all 12 breakthrough features.

Last Updated: October 24, 2025