HeliosDB Frequently Asked Questions (FAQ)

HeliosDB Frequently Asked Questions (FAQ)

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

---

Table of Contents

• General Questions
• Getting Started
• Features & Capabilities
• Performance & Scalability
• Data Management
• Security & Compliance
• Operations & Deployment
• Troubleshooting
• Licensing & Support

---

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.

Does HeliosDB support vector search?

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?

• User Guides: docs/user-guide/
• API Reference: docs/api/
• Tutorials: docs/tutorials/
• Architecture: docs/ARCHITECTURE.md
• Release Notes: docs/releases/

---

Additional Resources

• Getting Started Guide
• Connection Guide
• Query Guide
• Data Types Reference
• Feature Catalog
• Roadmap

---

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