---
title: "Configuration"
description: "HeliosDB Lite configuration file reference: storage, server, encryption, performance, authentication, compression, vector, session and quota settings."
---

# Configuration File Reference

## Overview

HeliosDB-Lite uses TOML configuration files for server-wide settings. This page is the reference for the configuration options in `config.toml`.

## Quick Start

```bash
# Copy example configuration
cp config.example.toml config.toml

# Edit configuration
nano config.toml

# Start server with configuration (the server refuses to start without a REST signing secret)
export HELIOSDB_JWT_SECRET="$(openssl rand -hex 32)"
heliosdb-lite start --config config.toml
```

## Configuration Sections

- [Storage](#storage-section)
- [Encryption](#encryption-section)
- [Server](#server-section)
- [Performance](#performance-section)
- [Optimizer](#optimizer-section)
- [Authentication](#authentication-section)
- [Compression](#compression-section)
- [Materialized Views](#materialized-views-section)
- [Vector Indexes](#vector-section)
- [Session](#session-section)
- [Locks](#locks-section)
- [Dump](#dump-section)
- [Resource Quotas](#resource-quotas-section)

## Storage Section

Controls database storage, WAL, and persistence.

```toml
[storage]
path = "./heliosdb-data"
memory_only = false
wal_enabled = true
wal_sync_mode = "sync"
cache_size = 536870912
compression = "Zstd"
time_travel_enabled = true
query_timeout_ms = 300000
statement_timeout_ms = 300000
transaction_isolation = "READ_COMMITTED"
```

### Options

| Option | Type | Default | Description |
|--------|------|---------|-------------|
| `path` | String | `"./heliosdb-data"` | Database directory path |
| `memory_only` | Boolean | `false` | Use in-memory database |
| `wal_enabled` | Boolean | `true` | Enable write-ahead log |
| `wal_sync_mode` | String | `"sync"` | WAL sync mode: `sync`, `async`, `group_commit` |
| `cache_size` | Integer | `536870912` | Cache size in bytes (512MB) |
| `compression` | String | `"Zstd"` | Default compression: `None`, `Zstd`, `Lz4` |
| `time_travel_enabled` | Boolean | `true` | Enable automatic versioning |
| `query_timeout_ms` | Integer | `300000` | Query timeout in milliseconds (5 minutes). Raise it for long batch work; `0` is not "unlimited", it times out every scanning query at once |
| `statement_timeout_ms` | Integer | `300000` | Per-statement timeout; planned, the setting is accepted but not enforced yet |
| `transaction_isolation` | String | `"READ_COMMITTED"` | Isolation level |

### Examples

```toml
# Development: In-memory database
[storage]
memory_only = true
wal_enabled = false

# Production: Durable, fast
[storage]
path = "/var/lib/heliosdb"
wal_sync_mode = "group_commit"
query_timeout_ms = 30000
cache_size = 2147483648  # 2GB

# Write-heavy: Async WAL
[storage]
wal_sync_mode = "async"
time_travel_enabled = false
```

## Encryption Section

Transparent data encryption (TDE) configuration.

```toml
[encryption]
enabled = false
algorithm = "Aes256Gcm"
rotation_interval_days = 90

[encryption.key_source]
Environment = "HELIOSDB_ENCRYPTION_KEY"
```

### Options

| Option | Type | Default | Description |
|--------|------|---------|-------------|
| `enabled` | Boolean | `false` | Enable encryption at rest |
| `algorithm` | String | `"Aes256Gcm"` | Encryption algorithm |
| `rotation_interval_days` | Integer | `90` | Key rotation interval |
| `key_source` | Object | Environment variable | Key source configuration |

### Key Source Options

```toml
# Option 1: Environment variable
[encryption.key_source]
Environment = "HELIOSDB_ENCRYPTION_KEY"

# Option 2: File
[encryption.key_source]
File = "/secure/path/to/key"

# Option 3: Cloud KMS
[encryption.key_source.Kms]
provider = "aws"
key_id = "arn:aws:kms:us-east-1:123:key/abc"
```

## Server Section

Network server configuration.

```toml
[server]
listen_addr = "127.0.0.1"
port = 5432
oracle_port = 1521        # planned: the Oracle listener is not started yet
max_connections = 100
tls_enabled = false
tls_cert_path = "/path/to/cert.pem"
tls_key_path = "/path/to/key.pem"
```

### Options

| Option | Type | Default | Description |
|--------|------|---------|-------------|
| `listen_addr` | String | `"127.0.0.1"` | Listen address (`0.0.0.0` for all) |
| `port` | Integer | `5432` | PostgreSQL protocol port |
| `oracle_port` | Integer | None (off) | Planned. Oracle TNS listener port (for example `1521`); the current release reads the key but does not start the listener, and a `start --oracle-port` flag is planned. Logons use Lite roles; see the [Oracle Protocol Quick Reference](/docs/lite/guides/quickstart/oracle_quick_reference/) |
| `oracle_idle_timeout_ms` (planned) | Integer | `300000` | Idle time allowed between requests on an Oracle session |
| `oracle_auth_timeout_ms` (planned) | Integer | `60000` | Deadline from accept to completed Oracle logon |
| `oracle_max_open_cursors` (planned) | Integer | `300` | Open cursors per Oracle session (then `ORA-01000`) |
| `oracle_max_request_bytes` (planned) | Integer | `268435456` | Largest single Oracle request (SQL and binds) |
| `oracle_session_kdf_iterations` (planned) | Integer | `3` | PBKDF2 rounds of the per-logon session key |
| `max_connections` | Integer | `100` | Maximum connections |
| `tls_enabled` | Boolean | `false` | Enable TLS/SSL |
| `tls_cert_path` | String | None | TLS certificate path |
| `tls_key_path` | String | None | TLS private key path |

### Examples

```toml
# Local development
[server]
listen_addr = "127.0.0.1"
port = 5432
max_connections = 10

# Production
[server]
listen_addr = "0.0.0.0"
port = 5432
max_connections = 1000
tls_enabled = true
tls_cert_path = "/etc/heliosdb/ssl/cert.pem"
tls_key_path = "/etc/heliosdb/ssl/key.pem"
```

## Performance Section

Performance tuning parameters.

```toml
[performance]
worker_threads = 0
query_timeout_secs = 300
simd_enabled = true
parallel_query = true
```

### Options

| Option | Type | Default | Description |
|--------|------|---------|-------------|
| `worker_threads` | Integer | CPU count | Worker threads (0 = auto) |
| `query_timeout_secs` | Integer | `300` | Legacy timeout setting |
| `simd_enabled` | Boolean | `true` | Enable SIMD optimizations |
| `parallel_query` | Boolean | `true` | Enable parallel execution |

## Optimizer Section

Query optimizer configuration.

```toml
[optimizer]
enabled = true
enable_seqscan = true
enable_indexscan = true
enable_hashjoin = true
enable_mergejoin = true
enable_nestloop = true
seq_page_cost = 1.0
random_page_cost = 4.0
cpu_tuple_cost = 0.01
cpu_index_tuple_cost = 0.005
```

### Options

| Option | Type | Default | Description |
|--------|------|---------|-------------|
| `enabled` | Boolean | `true` | Enable optimizer |
| `enable_seqscan` | Boolean | `true` | Allow sequential scans |
| `enable_indexscan` | Boolean | `true` | Allow index scans |
| `enable_hashjoin` | Boolean | `true` | Allow hash joins |
| `enable_mergejoin` | Boolean | `true` | Allow merge joins |
| `enable_nestloop` | Boolean | `true` | Allow nested loop joins |
| `seq_page_cost` | Float | `1.0` | Sequential page cost |
| `random_page_cost` | Float | `4.0` | Random page cost |
| `cpu_tuple_cost` | Float | `0.01` | CPU tuple cost |
| `cpu_index_tuple_cost` | Float | `0.005` | CPU index tuple cost |

### Examples

```toml
# SSD optimized
[optimizer]
random_page_cost = 1.1  # Low for SSDs

# Force index usage
[optimizer]
enable_seqscan = false

# Disable specific joins
[optimizer]
enable_hashjoin = false
enable_mergejoin = false
```

## Authentication Section

User authentication configuration.

```toml
[authentication]
enabled = false
method = "trust"
jwt_secret = "secret-key"
jwt_expiration_secs = 86400
password_hash_algorithm = "argon2"
users_file = "/etc/heliosdb/users.json"
```

### Options

| Option | Type | Default | Description |
|--------|------|---------|-------------|
| `enabled` | Boolean | `false` | Enable authentication |
| `method` | String | `"trust"` | Auth method: `trust`, `password`, `jwt`, `ldap` |
| `jwt_secret` | String | None | JWT secret key |
| `jwt_expiration_secs` | Integer | `86400` | JWT expiration (24h) |
| `password_hash_algorithm` | String | `"argon2"` | Hash: `argon2`, `bcrypt`, `pbkdf2` |
| `users_file` | String | None | Users database file |

### Examples

```toml
# Development: No auth
[authentication]
method = "trust"

# Production: JWT auth
[authentication]
enabled = true
method = "jwt"
jwt_secret = "CHANGE-THIS-IN-PRODUCTION"
jwt_expiration_secs = 3600  # 1 hour

# Password auth
[authentication]
enabled = true
method = "password"
password_hash_algorithm = "argon2"
users_file = "/etc/heliosdb/users.json"
```

## Compression Section

Data compression configuration.

```toml
[compression]
default_type = "Zstd"
level = 3
enable_alp = true
enable_fsst = true
min_size_bytes = 1024
```

### Options

| Option | Type | Default | Description |
|--------|------|---------|-------------|
| `default_type` | String | `"Zstd"` | Default compression type |
| `level` | Integer | `3` | Compression level (1-22) |
| `enable_alp` | Boolean | `true` | Enable ALP for numerics |
| `enable_fsst` | Boolean | `true` | Enable FSST for strings |
| `min_size_bytes` | Integer | `1024` | Minimum size to compress |

### Examples

```toml
# Maximum compression
[compression]
default_type = "Zstd"
level = 19

# Fast compression
[compression]
default_type = "Lz4"
level = 1

# No compression
[compression]
default_type = "None"
```

## Materialized Views Section

Materialized view refresh configuration. The section is accepted and its values are
stored, but the server does not run the background refresh worker yet: automatic refresh
is planned. Refresh views with `REFRESH MATERIALIZED VIEW` today.

```toml
[materialized_views]
auto_refresh_default = false
default_max_cpu_percent = 15
refresh_check_interval_secs = 60
max_concurrent_refreshes = 2
```

### Options

| Option | Type | Default | Description |
|--------|------|---------|-------------|
| `auto_refresh_default` | Boolean | `false` | Default auto-refresh |
| `default_max_cpu_percent` | Integer | `15` | Max CPU for refresh |
| `refresh_check_interval_secs` | Integer | `60` | Check interval |
| `max_concurrent_refreshes` | Integer | `2` | Concurrent refreshes |

## Vector Section

Vector index configuration.

```toml
[vector]
default_index_type = "hnsw"
hnsw_ef_construction = 200
hnsw_m = 16
enable_pq = true
pq_subvectors = 8
pq_bits = 8
```

### Options

| Option | Type | Default | Description |
|--------|------|---------|-------------|
| `default_index_type` | String | `"hnsw"` | Index type: `flat`, `hnsw`, `ivf` |
| `hnsw_ef_construction` | Integer | `200` | HNSW construction param |
| `hnsw_m` | Integer | `16` | HNSW connections |
| `enable_pq` | Boolean | `true` | Enable product quantization |
| `pq_subvectors` | Integer | `8` | PQ subvector count |
| `pq_bits` | Integer | `8` | PQ bits per subvector |

### Examples

```toml
# High quality index
[vector]
hnsw_ef_construction = 400
hnsw_m = 32

# Fast, low memory
[vector]
hnsw_ef_construction = 100
hnsw_m = 8
enable_pq = true
```

## Session Section

Session management configuration.

```toml
[session]
timeout_secs = 3600
max_sessions_per_user = 10
cleanup_interval_secs = 300
```

### Options

| Option | Type | Default | Description |
|--------|------|---------|-------------|
| `timeout_secs` | Integer | `3600` | Session timeout in seconds (1 hour) |
| `max_sessions_per_user` | Integer | `10` | Maximum concurrent sessions per user |
| `cleanup_interval_secs` | Integer | `300` | Cleanup check interval (5 minutes) |

### Examples

```toml
# Short-lived sessions (API use)
[session]
timeout_secs = 900
max_sessions_per_user = 100

# Long-lived sessions (interactive)
[session]
timeout_secs = 86400
max_sessions_per_user = 5
```

## Locks Section

Lock management and deadlock detection configuration.

```toml
[locks]
timeout_ms = 30000
deadlock_check_interval_ms = 100
max_lock_holders = 10000
```

### Options

| Option | Type | Default | Description |
|--------|------|---------|-------------|
| `timeout_ms` | Integer | `30000` | Lock acquisition timeout (30 seconds) |
| `deadlock_check_interval_ms` | Integer | `100` | Deadlock detection interval |
| `max_lock_holders` | Integer | `10000` | Maximum concurrent lock holders |

### Examples

```toml
# High-concurrency workload
[locks]
timeout_ms = 60000
deadlock_check_interval_ms = 50
max_lock_holders = 50000

# Low-latency requirements
[locks]
timeout_ms = 5000
deadlock_check_interval_ms = 10
```

## Dump Section

Database backup and dump scheduling configuration.

```toml
[dump]
auto_dump_enabled = false
schedule = ""
compression = "zstd"
max_dump_size_mb = 10000
keep_dumps = 10
dump_dir = ".dumps"
```

### Options

| Option | Type | Default | Description |
|--------|------|---------|-------------|
| `auto_dump_enabled` | Boolean | `false` | Enable scheduled dumps |
| `schedule` | String | `""` | Cron-style schedule (e.g., `"0 */6 * * *"`) |
| `compression` | String | `"zstd"` | Compression: `zstd`, `gzip`, `none` |
| `max_dump_size_mb` | Integer | `10000` | Max dump file size before rolling |
| `keep_dumps` | Integer | `10` | Number of old dumps to keep (0 = all) |
| `dump_dir` | String | `".dumps"` | Directory to store dump files |

### Examples

```toml
# Hourly automated dumps
[dump]
auto_dump_enabled = true
schedule = "0 * * * *"
compression = "zstd"
keep_dumps = 24

# Daily dumps with maximum compression
[dump]
auto_dump_enabled = true
schedule = "0 2 * * *"
compression = "zstd"
max_dump_size_mb = 50000
keep_dumps = 30
dump_dir = "/var/backups/heliosdb"

# No auto-dump, manual only
[dump]
auto_dump_enabled = false
compression = "gzip"
```

### Cron Schedule Format

```
┌───────────── minute (0 - 59)
│ ┌───────────── hour (0 - 23)
│ │ ┌───────────── day of month (1 - 31)
│ │ │ ┌───────────── month (1 - 12)
│ │ │ │ ┌───────────── day of week (0 - 6, Sunday = 0)
│ │ │ │ │
* * * * *

Examples:
  "0 */6 * * *"  - Every 6 hours
  "0 2 * * *"    - Daily at 2:00 AM
  "0 0 * * 0"    - Weekly on Sunday at midnight
  "*/15 * * * *" - Every 15 minutes
```

## Resource Quotas Section

Per-user resource limits and quotas.

```toml
[resource_quotas]
memory_limit_per_user_mb = 1024
max_concurrent_queries = 100
query_timeout_secs = 300
```

### Options

| Option | Type | Default | Description |
|--------|------|---------|-------------|
| `memory_limit_per_user_mb` | Integer | `1024` | Memory limit per user (1 GB) |
| `max_concurrent_queries` | Integer | `100` | Maximum concurrent queries per user |
| `query_timeout_secs` | Integer | `300` | Query execution timeout (5 minutes) |

### Examples

```toml
# Multi-tenant with strict limits
[resource_quotas]
memory_limit_per_user_mb = 256
max_concurrent_queries = 10
query_timeout_secs = 60

# Analytics workload (generous limits)
[resource_quotas]
memory_limit_per_user_mb = 8192
max_concurrent_queries = 20
query_timeout_secs = 3600
```

## Complete Configuration Examples

### Development

```toml
[storage]
memory_only = true
wal_enabled = false

[server]
listen_addr = "127.0.0.1"
port = 5432

[authentication]
method = "trust"

[performance]
worker_threads = 2
```

### Production

```toml
[storage]
path = "/var/lib/heliosdb"
wal_sync_mode = "group_commit"
query_timeout_ms = 30000
cache_size = 2147483648

[encryption]
enabled = true
[encryption.key_source]
Environment = "HELIOSDB_KEY"

[server]
listen_addr = "0.0.0.0"
max_connections = 1000
tls_enabled = true
tls_cert_path = "/etc/heliosdb/ssl/cert.pem"
tls_key_path = "/etc/heliosdb/ssl/key.pem"

[authentication]
enabled = true
method = "jwt"
jwt_secret = "CHANGE-THIS"

# Built-in audit logging is planned: the [audit] section is accepted
# but has no effect yet. See Audit Logging for trigger-based change records.
```

### High-Performance SSD

```toml
[storage]
cache_size = 4294967296  # 4GB

[optimizer]
random_page_cost = 1.1

[performance]
worker_threads = 0
simd_enabled = true

[compression]
default_type = "Lz4"
level = 1
```

## See Also

- [Deployment Guide](https://www.heliosdb.com/docs/lite/getting-started/deployment/) - Production deployment