---
title: "HeliosDB Configuration Quick Reference"
---

# HeliosDB Configuration Quick Reference

> **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.

**Quick access to common configuration patterns**

## Quick Configurations

### GPU Acceleration

:::caution[GPU acceleration: builds on request]
GPU acceleration (NVIDIA CUDA) is available in HeliosDB Full builds on request and
is not enabled in the public release build; AMD ROCm support is planned. In
the public release build, queries run on the CPU and the GPU settings and commands on
this page have no effect. Contact [sales@heliosdb.com](mailto:sales@heliosdb.com)
about a CUDA-enabled build.
:::

```toml
[gpu]
enabled = true
memory_limit = 8589934592  # 8GB
device_id = 0
fallback_to_cpu = true
```

Or via environment:
```bash
export HELIOSDB_GPU_ENABLED=true
export HELIOSDB_GPU_DEVICE_ID=0
```

### Multi-Region (2 Regions)

```toml
[multi_region]
enabled = true
primary_region = "us-west"

[[multi_region.regions]]
id = "us-west"
endpoint = "https://us-west.db.com"
is_primary = true

[[multi_region.regions]]
id = "us-east"
endpoint = "https://us-east.db.com"
is_primary = false
```

### Autoscaling

```toml
[autoscale]
enabled = true
min_cu = 10.0
max_cu = 1000.0
target_cpu_percent = 70.0
```

### CDC to Kafka (planned)

CDC connectors are planned; the current server does not act on the `[cdc]` section or the `HELIOSDB_CDC_*` variables.

```toml
[cdc]
enabled = true
output_format = "avro"

[cdc.kafka]
bootstrap_servers = ["localhost:9092"]
topic = "heliosdb-cdc"
```

## Environment Variables Cheat Sheet

```bash
# GPU
HELIOSDB_GPU_ENABLED=true
HELIOSDB_GPU_DEVICE_ID=0
HELIOSDB_GPU_MEMORY_LIMIT=8589934592

# Multi-Region
HELIOSDB_MULTIREGION_ENABLED=true
HELIOSDB_MULTIREGION_PRIMARY_REGION=us-west

# Autoscale
HELIOSDB_AUTOSCALE_ENABLED=true
HELIOSDB_AUTOSCALE_MIN_CU=10
HELIOSDB_AUTOSCALE_MAX_CU=1000

# CDC (planned connectors)
HELIOSDB_CDC_ENABLED=true
HELIOSDB_CDC_BUFFER_SIZE=10000

# Storage
HELIOSDB_STORAGE_DATA_DIR=/var/lib/heliosdb

# Network
HELIOSDB_NETWORK_LISTEN_ADDR=0.0.0.0:6543
```

## Common Patterns

### Development

```toml
[gpu]
enabled = false

[autoscale]
enabled = false

[multi_region]
enabled = false

[cdc]
enabled = false
```

### Production (Single Region)

```toml
[gpu]
enabled = true
fallback_to_cpu = true

[autoscale]
enabled = true
min_cu = 50
max_cu = 2000

[security]
tde_enabled = true
```

### Production (Multi-Region HA)

```toml
[gpu]
enabled = true

[multi_region]
enabled = true
replication_mode = "active_active"
auto_failover = true

[autoscale]
enabled = true
horizontal.enabled = true

[cdc]
enabled = true
```

### Serverless

```toml
[autoscale]
enabled = true
min_cu = 0  # Scale to zero
max_cu = 500
scale_to_zero_idle_seconds = 300
```

## Configuration Validation

```bash
# Test configuration
heliosdb config validate /etc/heliosdb/heliosdb.toml

# Show effective configuration (with env overrides)
heliosdb config show

# Generate example
heliosdb config generate > heliosdb.toml
```

## Priority Order

1. Environment Variables (highest)
2. TOML File
3. Defaults (lowest)

## Troubleshooting

```bash
# Check config is valid
heliosdb config validate

# View parsed config
heliosdb config show --format json

# Check GPU detection
heliosdb config check-gpu

# Test multi-region connectivity
heliosdb config test-regions
```

## Full Documentation

See Configuration Guide for complete details.