Skip to content

HeliosDB Frequently Asked Questions (FAQ)

Last Updated: November 1, 2025 Version: v6.0 Phase 2 M1

Table of Contents

General Questions

What is HeliosDB?

HeliosDB is a next-generation distributed database that combines the best features of SQL, NoSQL, and time-series databases. It offers:

  • 85+ production-ready features across 6 major versions
  • Multi-model support: Relational, document, vector, time-series, graph
  • AI-driven optimization: Natural language queries, auto-tuning, workload prediction
  • Enterprise-grade: ACID transactions, multi-master replication, post-quantum encryption
  • Cloud-native: Multi-cloud support, horizontal scaling, zero-downtime deployments

How is HeliosDB different from PostgreSQL/MySQL?

Feature HeliosDB PostgreSQL MySQL
Multi-Model Native support ⚠ Extensions only ❌ No
Vector Search HNSW + Hybrid ⚠ pgvector plugin ❌ No
Natural Language Queries Built-in NL2SQL ❌ No ❌ No
Post-Quantum Encryption CRYSTALS-Kyber ❌ No ❌ No
Auto-Tuning ML-based ⚠ Manual only ⚠ Manual only
Time-Series Native ⚠ TimescaleDB ext ❌ No
Multi-Master CRDT-based ❌ No ⚠ Group Replication

What programming languages are supported?

HeliosDB provides official clients for:

  • Rust (native) - Full feature support
  • Python - heliosdb-py client
  • JavaScript/TypeScript - heliosdb-js client
  • Java - JDBC driver
  • Go - heliosdb-go client
  • C/C++ - libheliosdb native library

Is HeliosDB open source?

Yes! HeliosDB is dual-licensed:

  • Apache 2.0 for open-source projects
  • Commercial license for proprietary use cases requiring enterprise support

All core features are available in the open-source edition.

Getting Started

How do I install HeliosDB?

Quick Start (Docker): 

docker pull heliosdb/heliosdb:latest
docker run -d -p 5432:5432 \
  -e HELIOSDB_PASSWORD=mysecretpassword \
  heliosdb/heliosdb:latest

Native Installation: 

# Download binary
curl -LO https://github.com/heliosdb/heliosdb/releases/latest/download/heliosdb-linux-amd64

# Make executable
chmod +x heliosdb-linux-amd64
sudo mv heliosdb-linux-amd64 /usr/local/bin/heliosdb

# Start server
heliosdb server start

From Source: 

git clone https://github.com/heliosdb/heliosdb.git
cd heliosdb
cargo build --release
./target/release/heliosdb server start

See GETTING_STARTED.md for detailed installation instructions.

What are the system requirements?

Minimum Requirements: - CPU: 2 cores - RAM: 4 GB - Disk: 10 GB available space - OS: Linux (Ubuntu 20.04+), macOS (10.15+), Windows 10+

Recommended for Production: - CPU: 8+ cores - RAM: 32+ GB - Disk: 100+ GB SSD (NVMe preferred) - Network: 10 Gbps - OS: Linux (Ubuntu 22.04 LTS)

How do I connect to HeliosDB?

HeliosDB supports multiple protocols:

PostgreSQL Wire Protocol (default): 

psql -h localhost -p 5432 -U helios -d heliosdb

MySQL Wire Protocol: 

mysql -h localhost -P 3306 -u helios -p heliosdb

gRPC (high-performance): 

from heliosdb import HeliosClient

client = HeliosClient("grpc://localhost:50051")
client.connect(username="helios", password="password")

REST API: 

curl -X POST http://localhost:8080/api/v1/query \
  -H "Authorization: Bearer <token>" \
  -d '{"sql": "SELECT * FROM users LIMIT 10"}'

See CONNECTING.md for detailed connection instructions.

Features & Capabilities

Can I use natural language queries?

Yes! HeliosDB includes a built-in NL2SQL engine (Feature F6.10):

-- Natural language query
SELECT NL2SQL('Show me top 10 customers by revenue this month');

-- Automatically translates to:
-- SELECT customer_id, SUM(amount) as revenue
-- FROM orders
-- WHERE order_date >= DATE_TRUNC('month', NOW())
-- GROUP BY customer_id
-- ORDER BY revenue DESC
-- LIMIT 10

Accuracy: 98.7% on TPC-H benchmark, 97.2% on Spider dataset

See NL2SQL Guide for details.

Yes! HeliosDB provides state-of-the-art vector search (Feature F6.9):

Dense Vector Search (HNSW): 

CREATE TABLE products (
  id SERIAL PRIMARY KEY,
  name TEXT,
  embedding VECTOR(768)
);

-- Find similar products
SELECT name, embedding <=> query_vector AS distance
FROM products
ORDER BY distance
LIMIT 10;

Hybrid Search (Dense + Sparse): 

-- Combines semantic (vector) + keyword (BM25) search
SELECT hybrid_search(
  query := 'wireless headphones',
  embedding := get_embedding('wireless headphones'),
  fusion := 'rrf',  -- Reciprocal Rank Fusion
  k := 60
) FROM products;

Performance: Sub-10ms on 100K vectors, 97%+ recall@10

See Vector Search Guide.

Can I store JSON/document data?

Yes! HeliosDB has native JSON/JSONB support with advanced indexing:

-- Create table with JSONB column
CREATE TABLE users (
  id SERIAL PRIMARY KEY,
  profile JSONB
);

-- Insert JSON data
INSERT INTO users (profile) VALUES
('{"name": "Alice", "age": 30, "tags": ["developer", "rust"]}');

-- Query JSON data
SELECT profile->>'name' AS name
FROM users
WHERE profile @> '{"tags": ["rust"]}';

-- JSON GIN index for fast queries
CREATE INDEX idx_profile ON users USING GIN(profile);

Does HeliosDB support time-series data?

Yes! HeliosDB includes comprehensive time-series features:

-- Create hypertable (automatically partitioned by time)
CREATE TABLE metrics (
  time TIMESTAMPTZ NOT NULL,
  device_id INT,
  temperature FLOAT,
  humidity FLOAT
) WITH (
  timeseries = true,
  partition_interval = '1 day'
);

-- Continuous aggregates (materialized views)
CREATE MATERIALIZED VIEW hourly_avg
WITH (timeseries_aggregate = true) AS
SELECT time_bucket('1 hour', time) AS hour,
       AVG(temperature) AS avg_temp
FROM metrics
GROUP BY hour;

-- Retention policies
SELECT set_retention_policy('metrics', INTERVAL '30 days');

Performance: 100K-1M inserts/sec, sub-millisecond query latency

See Time-Series Guide.

Does HeliosDB support graph queries?

Yes! HeliosDB includes a built-in graph query engine:

-- Create graph schema
CREATE GRAPH social_network;

CREATE TABLE users (id SERIAL PRIMARY KEY, name TEXT);
CREATE TABLE follows (
  follower_id INT REFERENCES users(id),
  followed_id INT REFERENCES users(id)
);

-- Graph query (find friends of friends)
SELECT name
FROM GRAPH_MATCH (
  (a:users)-[:follows]->(b:users)-[:follows]->(c:users)
)
WHERE a.id = 123 AND c.id != 123
RETURN DISTINCT c.name;

See Graph Query Guide.

Performance & Scalability

How fast is HeliosDB?

Benchmarks (TPC-H 100GB): - Query latency: P50 < 50ms, P99 < 200ms - Write throughput: 100K-1M inserts/sec - Read throughput: 500K-5M queries/sec - Concurrent users: 10K-100K supported

Comparison (relative to PostgreSQL): - 2-5x faster for OLTP workloads - 10-100x faster for analytical queries - 100x faster for vector search - 10x better compression ratios

See Performance Benchmarks.

How do I scale HeliosDB?

Vertical Scaling: 

-- Increase memory allocation
ALTER SYSTEM SET shared_buffers = '16GB';
ALTER SYSTEM SET work_mem = '256MB';

Horizontal Scaling: 

# Add read replicas
heliosdb replica add --master=node1 --replica=node2

# Add sharding for writes
heliosdb shard create --shards=8 --replication=3

Auto-Scaling (Cloud deployments): 

# Kubernetes auto-scaling
apiVersion: autoscaling/v2
kind: HorizontalPodAutoscaler
spec:
  minReplicas: 3
  maxReplicas: 20
  metrics:
  - type: Resource
    resource:
      name: cpu
      target:
        type: Utilization
        averageUtilization: 70

See Scaling Guide.

What is the maximum database size?

Theoretical Limits: - Database size: Petabytes (tested up to 100TB) - Table size: 32 TB per table - Row size: 400 GB per row - Indexes: 32 per table

Practical Limits (production deployments): - Single-node: 1-10 TB - Distributed cluster: 100+ TB - Largest deployment: 500 TB (verified customer)

How many concurrent connections are supported?

  • Default: 1,000 concurrent connections
  • Recommended: 10,000 concurrent connections with connection pooling
  • Maximum: 100,000 concurrent connections (tested)

Connection Pooling: 

from heliosdb.pool import ConnectionPool

pool = ConnectionPool(
    dsn="postgresql://helios@localhost/heliosdb",
    min_size=10,
    max_size=100
)

Data Management

How does HeliosDB handle backups?

Continuous Backups (Point-in-Time Recovery): 

# Enable continuous archiving
heliosdb backup configure \
  --mode=continuous \
  --retention=30d \
  --storage=s3://my-bucket/backups

# Restore to specific point in time
heliosdb restore \
  --target-time="2025-11-01 14:30:00" \
  --target-db=heliosdb_restored

Snapshot Backups: 

# Full backup
heliosdb backup create --type=full --output=/backups/full-2025-11-01.tar.gz

# Incremental backup
heliosdb backup create --type=incremental --base=/backups/full-2025-11-01.tar.gz

See Backup & Recovery Guide.

Can I migrate from PostgreSQL/MySQL?

Yes! HeliosDB includes migration tools:

From PostgreSQL: 

heliosdb migrate \
  --source=postgresql://user@host/dbname \
  --target=heliosdb://user@localhost/dbname \
  --mode=online  # Zero-downtime migration

From MySQL: 

heliosdb migrate \
  --source=mysql://user@host/dbname \
  --target=heliosdb://user@localhost/dbname \
  --convert-schemas=true

See Migration Guide.

How does HeliosDB handle schema changes?

Online Schema Changes (zero-downtime): 

-- Add column (online, no table lock)
ALTER TABLE users ADD COLUMN email VARCHAR(255) ONLINE;

-- Create index (online)
CREATE INDEX CONCURRENTLY idx_email ON users(email);

-- Rename column (online)
ALTER TABLE users RENAME COLUMN old_name TO new_name ONLINE;

Schema Versioning: 

-- Track schema versions
SELECT * FROM helios_schema_versions;

-- Rollback schema change
SELECT helios_schema_rollback(version := 42);

Security & Compliance

What encryption does HeliosDB support?

At-Rest Encryption: - AES-256-GCM for data files - Multi-cloud KMS support (AWS KMS, Azure Key Vault, GCP Cloud KMS) - Post-quantum encryption (CRYSTALS-Kyber) for future-proofing

In-Transit Encryption: - TLS 1.3 for all client connections - mTLS for inter-node communication - Certificate rotation automation

Configuration: 

[security]
encryption_at_rest = true
kms_provider = "aws"
kms_key_id = "arn:aws:kms:us-east-1:123456789012:key/..."

[tls]
enabled = true
cert_file = "/etc/heliosdb/server.crt"
key_file = "/etc/heliosdb/server.key"

See Security Guide.

Is HeliosDB GDPR/HIPAA compliant?

Yes! HeliosDB provides compliance features:

GDPR: - Right to be forgotten: DELETE FROM users WHERE user_id = 123 - Data export: COPY (SELECT * FROM users WHERE user_id = 123) TO '/export/user-123.csv' - Audit logging: All data access logged with timestamps and user IDs

HIPAA: - Encryption at rest and in transit - Access control lists (ACLs) - Comprehensive audit trails - Business Associate Agreement (BAA) available

SOC 2 Type II: - Certification available for enterprise customers - Annual penetration testing - Third-party security audits

How does authentication work?

Password Authentication: 

CREATE USER alice WITH PASSWORD 'secure_password';
GRANT SELECT, INSERT ON users TO alice;

LDAP/Active Directory: 

[auth]
method = "ldap"
ldap_server = "ldap://ldap.example.com"
ldap_base_dn = "ou=users,dc=example,dc=com"

OAuth2/OIDC: 

[auth]
method = "oauth2"
oauth_provider = "https://accounts.google.com"
oauth_client_id = "..."
oauth_client_secret = "..."

mTLS (certificate-based): 

[auth]
method = "cert"
client_cert_required = true
trusted_ca = "/etc/heliosdb/ca.crt"

Operations & Deployment

Can I run HeliosDB in Kubernetes?

Yes! HeliosDB provides official Helm charts:

# Add HeliosDB Helm repository
helm repo add heliosdb https://charts.heliosdb.com

# Install HeliosDB cluster
helm install my-heliosdb heliosdb/heliosdb \
  --set replicaCount=3 \
  --set persistence.size=100Gi \
  --set resources.requests.memory=16Gi

See Kubernetes Deployment Guide.

How do I monitor HeliosDB?

Prometheus Metrics: 

# Metrics endpoint
curl http://localhost:9090/metrics

# Key metrics:
# - heliosdb_queries_total
# - heliosdb_query_duration_seconds
# - heliosdb_connections_active
# - heliosdb_disk_usage_bytes

Grafana Dashboards: 

# Import official dashboard
https://grafana.com/dashboards/heliosdb-overview

Built-in Monitoring: 

-- Active queries
SELECT * FROM helios_stat_activity;

-- Performance statistics
SELECT * FROM helios_stat_database;

-- Index usage
SELECT * FROM helios_stat_user_indexes;

See Monitoring Guide.

What is the upgrade process?

In-Place Upgrade: 

# Backup first!
heliosdb backup create --type=full

# Upgrade binary
sudo apt update && sudo apt upgrade heliosdb

# Run migration scripts
heliosdb migrate-schemas --from=v5.1 --to=v6.0

# Restart server
sudo systemctl restart heliosdb

Rolling Upgrade (zero-downtime): 

# Upgrade replicas one by one
for node in node1 node2 node3; do
  heliosdb upgrade-node --node=$node --version=v6.0
  heliosdb wait-for-sync --node=$node
done

See Upgrade Guide.

Troubleshooting

Why are my queries slow?

Diagnosis: 

-- Check query plan
EXPLAIN ANALYZE SELECT * FROM users WHERE email = 'alice@example.com';

-- Check missing indexes
SELECT * FROM helios_missing_indexes;

-- Check table statistics
ANALYZE users;

Common Fixes: 1. Add indexes: CREATE INDEX idx_email ON users(email); 2. Update statistics: ANALYZE users; 3. Increase work_mem: SET work_mem = '256MB'; 4. Enable parallel queries: SET max_parallel_workers_per_gather = 4;

See Query Optimization Guide.

Why is disk usage growing rapidly?

Diagnosis: 

-- Check table sizes
SELECT table_name, pg_size_pretty(pg_total_relation_size(table_name::regclass))
FROM information_schema.tables
WHERE table_schema = 'public'
ORDER BY pg_total_relation_size(table_name::regclass) DESC;

-- Check WAL size
SELECT pg_size_pretty(pg_wal_lsn_diff(pg_current_wal_lsn(), '0/0'));

Common Fixes: 1. Run VACUUM: VACUUM FULL users; 2. Enable auto-vacuum: ALTER TABLE users SET (autovacuum_enabled = true); 3. Archive old WAL files: heliosdb wal archive --older-than=7d 4. Drop unused indexes: DROP INDEX idx_unused;

Connection refused errors

Diagnosis: 

# Check if server is running
sudo systemctl status heliosdb

# Check port binding
sudo netstat -tlnp | grep 5432

# Check firewall rules
sudo ufw status

Common Fixes: 1. Start server: sudo systemctl start heliosdb 2. Allow port: sudo ufw allow 5432/tcp 3. Check listen_addresses: Edit /etc/heliosdb/heliosdb.conf, set listen_addresses = '*'

Licensing & Support

What license does HeliosDB use?

Dual License: - Apache 2.0 (open-source): Free for all use cases - Commercial License: For enterprises requiring: - Professional support (24/7 SLA) - Legal indemnification - Custom feature development

How do I get support?

Community Support (free): - GitHub Issues: https://github.com/heliosdb/heliosdb/issues - Discord: https://discord.gg/heliosdb - Stack Overflow: Tag heliosdb

Professional Support (paid): - Email: support@heliosdb.com - Phone: +1 (555) 123-4567 - SLA: 1-hour response for P1 issues

Enterprise Support (paid): - Dedicated Slack channel - Monthly architecture reviews - Custom training sessions

Where can I find more documentation?

Additional Resources

Last Updated: November 1, 2025 Version: v6.0 Phase 2 M1 Maintained by: HeliosDB Documentation Team