HeliosDB Frequently Asked Questions (FAQ)

Container images: HeliosDB Full images are not published on Docker Hub or any other public registry. Images and Helm charts are provided through private registry access during onboarding: contact sales@heliosdb.com. The examples on this page use heliosdb-full:<tag>, an image built locally from the licensed source distribution (docker build -t heliosdb-full:<tag> .); replace it with the image reference you receive if you use the private registry.

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

General Questions

What is HeliosDB?

HeliosDB Full is a multi-model, multi-protocol database that combines the best features of SQL, NoSQL, and time-series databases. The current release runs as a single server; Raft clustering, multi-region replication and sharding are planned. It offers:

85+ features
Multi-model support: Relational, document, vector, time-series, graph
AI-driven optimization: Natural language queries, auto-tuning, workload prediction
Transactions: ACID transactions (multi-master replication and post-quantum encryption are planned)
Cloud-native: Multi-cloud support and zero-downtime deployments (horizontal scaling is planned)

How is HeliosDB different from PostgreSQL/MySQL?

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

What programming languages are supported?

Any PostgreSQL client library works over the PostgreSQL wire protocol (port 5432 by default). Use one of these:

Rust - tokio-postgres or sqlx
Python - psycopg
JavaScript/TypeScript - pg (node-postgres)
Java - the PostgreSQL JDBC driver
Go - pgx
C/C++ - libpq

The REST clients in the HeliosDB-SDKs repository (for example the Rust heliosdb-client crate, which is not on crates.io and installs with cargo add heliosdb-client --git https://github.com/HeliosDatabase/HeliosDB-SDKs) target the /v1/... API of HeliosDB Nano and Lite. HeliosDB Full does not serve that API, so use a PostgreSQL driver with Full.

Is HeliosDB open source?

HeliosDB Full is source-available under the Server Side Public License (SSPL-1.0), the same licence as HeliosDB Lite. HeliosDB Nano and HeliosProxy are Apache 2.0.

A commercial license is available for use cases that require enterprise support or terms other than SSPL — contact support@heliosdb.com.

Getting Started

How do I install HeliosDB?

Quick Start (Docker): HeliosDB Full images are not published on Docker Hub or any other public registry. Use the image reference you receive during onboarding, or build an image from the licensed source distribution with its Dockerfile:

docker build -t heliosdb-full:latest .
docker run -d -p 5432:5432 -p 8443:8443 \
  -e HELIOSDB_ALLOW_EXTERNAL=1 \
  heliosdb-full:latest

The image binds all interfaces inside the container, so it needs HELIOSDB_ALLOW_EXTERNAL=1 to start. The HTTP gateway listens on port 8443. For the superuser password and the other credentials, see the Quick Start.

Native binaries and source access: HeliosDB Full is distributed to licensed customers. Native binaries, container images and source access are provided during onboarding — contact sales@heliosdb.com for access.

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

From application code: use any PostgreSQL driver. HeliosDB Full does not expose a gRPC client API; the PostgreSQL wire protocol is the primary interface.

import psycopg  # pip install "psycopg[binary]"

conn = psycopg.connect("host=localhost port=5432 user=helios password=password dbname=heliosdb")
print(conn.execute("SELECT version()").fetchone())

// go get github.com/jackc/pgx/v5
conn, err := pgx.Connect(ctx, "postgres://helios:password@localhost:5432/heliosdb")

REST API:

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

See CONNECTING.md for detailed connection instructions.

Features & Capabilities

Can I use natural language queries?

HeliosDB includes a built-in NL2SQL engine:

-- 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 built-in vector search:

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?

HeliosDB has native JSON/JSONB support with 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?

HeliosDB includes 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?

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?

Indicative figures measured on representative fixtures; reproduce on your own hardware.

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 (planned):

HeliosDB Full runs as a single server. Read replicas, sharding, Raft clustering and multi-region replication are planned, and so is autoscaling across nodes. Until then, scale a server vertically (CPU, memory, faster disks), and run one server (one Kubernetes replica) per database: separate replicas of the server do not share or replicate data.

What is the maximum database size?

Theoretical Limits:

Database size: bounded by the storage attached to the server (tested up to 100 TB in internal tests)
Table size: 32 TB per table
Row size: 400 GB per row
Indexes: 32 per table

Practical Limits (production deployments):

Single server: 1-10 TB
Distributed cluster (planned with clustering): 100+ TB

How many concurrent connections are supported?

Default limit: 10,000 concurrent connections across all listeners (HELIOSDB_MAX_CONNECTIONS changes it)
Recommended: put a connection pool in front when many application processes connect
Tested maximum: 100,000 concurrent connections (internal tests)

Connection Pooling: use the pool of your PostgreSQL driver, or put HeliosProxy in front of the PostgreSQL listener.

# pip install "psycopg[binary,pool]"
from psycopg_pool import ConnectionPool

pool = ConnectionPool(
    "host=localhost port=5432 user=helios dbname=heliosdb",
    min_size=10,
    max_size=100,
)

Data Management

How does HeliosDB handle backups?

The heliosdb-full server has no backup subcommand. For a consistent copy, stop the server (it flushes storage when it stops) and copy its data directory, or take a snapshot of the volume. To restore, start heliosdb-full on the copy:

# Container: copy the data volume while the server is stopped
docker stop heliosdb
docker run --rm -v heliosdb-data:/data -v "$PWD":/backup alpine \
  tar czf /backup/heliosdb-data.tgz -C /data .
docker start heliosdb

# Binary: restore by starting the server on the copied directory
heliosdb-full --data-dir ./heliosdb-data-restored

Can I migrate from PostgreSQL/MySQL?

Yes. PostgreSQL and MySQL applications connect to the PostgreSQL and MySQL listeners with their existing drivers. The database migration guides walk through schema and data migration for each source database.

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): planned

In-Transit Encryption:

TLS: HeliosDB Full listeners do not terminate TLS; put a TLS-terminating proxy in front. Native PostgreSQL TLS is planned for the next release
mTLS for inter-node communication (planned with clustering)
Certificate rotation (planned with native TLS)

Configuration:

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

See Security Guide.

Is HeliosDB GDPR/HIPAA compliant?

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 (SCRAM-SHA-256 on the PostgreSQL listener):

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

LDAP/Active Directory (planned):

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

OAuth2/OIDC (planned):

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

mTLS (certificate-based, planned):

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

Operations & Deployment

Can I run HeliosDB in Kubernetes?

Yes. HeliosDB Full runs on Kubernetes. The Helm charts and container images are not on a public registry. They are provided during onboarding: contact sales@heliosdb.com for access. With the chart you receive, an install looks like this:

# Install HeliosDB Full from the chart provided during onboarding
helm install my-heliosdb ./heliosdb \
  --set replicaCount=1 \
  --set persistence.size=100Gi \
  --set resources.requests.memory=16Gi

HeliosDB Full runs as a single server, so keep one replica per database; multi-replica clusters are planned with Raft clustering.

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: stop the server, copy its data directory (or snapshot the volume), then start the new heliosdb-full binary or image on the same data directory:

# Container: stop, back up the volume, start the new image on the same volume
docker stop heliosdb
docker run --rm -v heliosdb-data:/data -v "$PWD":/backup alpine \
  tar czf /backup/heliosdb-data.tgz -C /data .
docker rm heliosdb
docker run -d --name heliosdb <the same -e, -p and -v options as before> <new-heliosdb-full-image>

# Binary: stop the old process, copy the data directory, start the new binary
heliosdb-full --data-dir ./heliosdb-data

Rolling Upgrade (zero-downtime): planned with clustering. A single server is upgraded in place as above.

Troubleshooting

Why are my queries slow?

ANALYZE in the current release: ANALYZE (including VACUUM ANALYZE) is accepted for PostgreSQL compatibility and returns immediately; it does not collect planner statistics yet. Statistics collection is planned. EXPLAIN ANALYZE, which runs the query and reports actual rows and timing, works today.

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:

Add indexes: CREATE INDEX idx_email ON users(email);
Update statistics: ANALYZE users;
Increase work_mem: SET work_mem = '256MB';
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:

Run VACUUM: VACUUM FULL users;
Enable auto-vacuum: ALTER TABLE users SET (autovacuum_enabled = true);
Drop unused indexes: DROP INDEX idx_unused;

Connection refused errors

Diagnosis:

# Check if the server is running (container, or the HTTP health probe)
docker ps --filter name=heliosdb
curl -s http://127.0.0.1:8443/health

# Check port binding
sudo ss -tlnp | grep 5432

# Check firewall rules
sudo ufw status

Common Fixes:

Start server: docker start heliosdb, or run heliosdb-full --data-dir <dir>
Allow port: sudo ufw allow 5432/tcp
Check the bind address: the server binds 127.0.0.1 by default. To accept remote clients, start it with --bind-addr <address> --allow-external (or HELIOSDB_BIND_ADDR and HELIOSDB_ALLOW_EXTERNAL=1)

Licensing & Support

What license does HeliosDB use?

SSPL-1.0 (source-available) for HeliosDB Full
Commercial License: For enterprises requiring:
- Professional support (24/7 SLA)
- Legal indemnification
- Custom feature development

How do I get support?

Community Support (free):

Discord: https://discord.gg/yTykuUrFXc

Professional Support (paid):

Email: support@heliosdb.com
SLA: 1-hour response for P1 issues

Enterprise Support (paid):

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/

HeliosDB Frequently Asked Questions (FAQ)

Table of Contents

General Questions

What is HeliosDB?

How is HeliosDB different from PostgreSQL/MySQL?

What programming languages are supported?

Is HeliosDB open source?

Getting Started

How do I install HeliosDB?

What are the system requirements?

How do I connect to HeliosDB?

Features & Capabilities

Can I use natural language queries?

Does HeliosDB support vector search?

Can I store JSON/document data?

Does HeliosDB support time-series data?

Does HeliosDB support graph queries?

Performance & Scalability

How fast is HeliosDB?

How do I scale HeliosDB?

What is the maximum database size?

How many concurrent connections are supported?

Data Management

How does HeliosDB handle backups?

Can I migrate from PostgreSQL/MySQL?

How does HeliosDB handle schema changes?

Security & Compliance

What encryption does HeliosDB support?

Is HeliosDB GDPR/HIPAA compliant?

How does authentication work?

Operations & Deployment

Can I run HeliosDB in Kubernetes?

How do I monitor HeliosDB?

What is the upgrade process?

Troubleshooting

Why are my queries slow?

Why is disk usage growing rapidly?

Connection refused errors

Licensing & Support

What license does HeliosDB use?

How do I get support?

Where can I find more documentation?

Additional Resources