---
title: "HeliosDB Frequently Asked Questions (FAQ)"
---

# 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](mailto: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.


---

## Table of Contents

- [General Questions](#general-questions)
- [Getting Started](#getting-started)
- [Features & Capabilities](#features--capabilities)
- [Performance & Scalability](#performance--scalability)
- [Data Management](#data-management)
- [Security & Compliance](#security--compliance)
- [Operations & Deployment](#operations--deployment)
- [Troubleshooting](#troubleshooting)
- [Licensing & Support](#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:

- **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](https://github.com/HeliosDatabase/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`:
```bash
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](/docs/full/quickstart/).

**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](mailto:sales@heliosdb.com) for access.

See [GETTING_STARTED.md](https://www.heliosdb.com/docs/full/guides/user/getting_started/) 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):
```bash
psql -h localhost -p 5432 -U helios -d heliosdb
```

**MySQL Wire Protocol**:
```bash
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.
```python
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
// go get github.com/jackc/pgx/v5
conn, err := pgx.Connect(ctx, "postgres://helios:password@localhost:5432/heliosdb")
```

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

See [CONNECTING.md](https://www.heliosdb.com/docs/full/guides/user/connecting/) for detailed connection instructions.

---

## Features & Capabilities

### Can I use natural language queries?

HeliosDB includes a built-in NL2SQL engine:

```sql
-- 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):
```sql
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):
```sql
-- 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:

```sql
-- 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:

```sql
-- 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:

```sql
-- 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** (internal tests, HeliosDB Full; 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** (internal tests, HeliosDB Full vs 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**:
```sql
-- 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
- 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

### 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

**Connection Pooling**: use the pool of your PostgreSQL driver, or put
[HeliosProxy](/docs/proxy/) in front of the PostgreSQL listener.
```python
# 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:

```bash
# 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](/docs/full/reference/protocols/migrations/readme/)
walk through schema and data migration for each source database.

### How does HeliosDB handle schema changes?

**Online Schema Changes** (zero-downtime):
```sql
-- 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**:
```sql
-- 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
- mTLS for inter-node communication (planned with clustering)
- Certificate rotation (planned with native TLS)

**Configuration**:
```toml
[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):
```sql
CREATE USER alice WITH PASSWORD 'secure_password';
GRANT SELECT, INSERT ON users TO alice;
```

:::caution[Planned]
LDAP/Active Directory, OAuth2/OIDC and certificate (mTLS) authentication are
planned and are not in the current release. The settings below show the planned
configuration; the current server does not read them.
:::

**LDAP/Active Directory** (planned):
```toml
[auth]
method = "ldap"
ldap_server = "ldap://ldap.example.com"
ldap_base_dn = "ou=users,dc=example,dc=com"
```

**OAuth2/OIDC** (planned):
```toml
[auth]
method = "oauth2"
oauth_provider = "https://accounts.google.com"
oauth_client_id = "..."
oauth_client_secret = "..."
```

**mTLS** (certificate-based, planned):
```toml
[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](mailto:sales@heliosdb.com) for access. With the chart you receive, an install looks like this:

```bash
# 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**:
```bash
# 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**:
```bash
# Import official dashboard
https://grafana.com/dashboards/heliosdb-overview
```

**Built-in Monitoring**:
```sql
-- 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:
```bash
# 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**:
```sql
-- 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**:
```sql
-- 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. **Drop unused indexes**: `DROP INDEX idx_unused;`

### Connection refused errors

**Diagnosis**:
```bash
# 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**:
1. **Start server**: `docker start heliosdb`, or run `heliosdb-full --data-dir <dir>`
2. **Allow port**: `sudo ufw allow 5432/tcp`
3. **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**: [User Guides](/docs/full/guides/user/)
- **API Reference**: docs/api/
- **Tutorials**: docs/tutorials/
- **Architecture**: docs/ARCHITECTURE.md
- **Release Notes**: docs/releases/

---

## Additional Resources

- [Getting Started Guide](https://www.heliosdb.com/docs/full/guides/user/getting_started/)
- [Connection Guide](https://www.heliosdb.com/docs/full/guides/user/connecting/)
- [Query Guide](https://www.heliosdb.com/docs/full/guides/user/querying/)
- [Data Types Reference](https://www.heliosdb.com/docs/full/guides/user/data_types/)

---