---
title: "Configuration Reference"
---

# Configuration Reference

## Table of Contents

1. [Overview](#overview)
2. [Configuration File Format](#configuration-file-format)
3. [Session Configuration](#session-configuration)
4. [Lock Manager Configuration](#lock-manager-configuration)
5. [Dump Configuration](#dump-configuration)
6. [Resource Quotas Configuration](#resource-quotas-configuration)
7. [Server Configuration](#server-configuration)
8. [Authentication Configuration](#authentication-configuration)
9. [Logging Configuration](#logging-configuration)
10. [Complete Configuration Example](#complete-configuration-example)
11. [Default Values Table](#default-values-table)
12. [Tuning Recommendations](#tuning-recommendations)
13. [Security Considerations](#security-considerations)
14. [Performance Tuning Tips](#performance-tuning-tips)

## Overview

HeliosDB Nano uses TOML format for configuration. Configuration files provide centralized control over:

- Session management and timeouts
- Lock manager behavior
- Dump/restore automation
- Resource quotas and limits
- Authentication and authorization
- Logging and monitoring

**Configuration File Locations (checked in order):**

1. Command-line: `--config /path/to/config.toml`
2. Environment: `$HELIOSDB_CONFIG`
3. Current directory: `./config.toml`
4. User home: `~/.config/heliosdb/config.toml`
5. System-wide: `/etc/heliosdb/config.toml`

**Loading Priority:**
- Command-line flags override config file
- Environment variables override config file
- Config file overrides built-in defaults

## Configuration File Format

**Basic Structure:**

```toml
# config.toml

[server]
# Server settings

[session]
# Session management

[locks]
# Lock manager

[dump]
# Dump/restore automation

[resource_quotas]
# Resource limits

[auth]
# Authentication

[logging]
# Logging configuration
```

**Validation:**

```bash
# Validate configuration file
heliosdb-nano config validate --config config.toml

# Show effective configuration (with overrides)
heliosdb-nano config show --config config.toml
```

## Session Configuration

Controls multi-user session management and transaction isolation.

### Configuration Section

```toml
[session]
# Session timeout in seconds (idle sessions terminated)
timeout_secs = 3600  # 1 hour

# Maximum sessions per user
max_sessions_per_user = 10

# Default isolation level for new sessions
# Options: "READ_COMMITTED", "REPEATABLE_READ", "SERIALIZABLE"
default_isolation_level = "READ_COMMITTED"

# Enable session statistics tracking
enable_stats = true

# Session cleanup interval (seconds)
cleanup_interval_secs = 300  # 5 minutes
```

### Options Reference

| Option | Type | Default | Description |
|--------|------|---------|-------------|
| `timeout_secs` | Integer | `3600` | Idle session timeout in seconds |
| `max_sessions_per_user` | Integer | `10` | Maximum concurrent sessions per user |
| `default_isolation_level` | String | `"READ_COMMITTED"` | Default transaction isolation level |
| `enable_stats` | Boolean | `true` | Track session statistics |
| `cleanup_interval_secs` | Integer | `300` | How often to check for expired sessions |

### Isolation Level Values

| Value | ANSI Level | Guarantees | Use Case |
|-------|------------|------------|----------|
| `READ_COMMITTED` | Read Committed | No dirty reads | Web apps, interactive queries |
| `REPEATABLE_READ` | Repeatable Read | Consistent snapshot | Reports, exports |
| `SERIALIZABLE` | Serializable | Full serializability | Financial transactions |

### Examples

**Development (permissive):**

```toml
[session]
timeout_secs = 28800  # 8 hours
max_sessions_per_user = 50
default_isolation_level = "READ_COMMITTED"
```

**Production (strict):**

```toml
[session]
timeout_secs = 1800  # 30 minutes
max_sessions_per_user = 5
default_isolation_level = "REPEATABLE_READ"
cleanup_interval_secs = 60
```

**High-concurrency (optimized):**

```toml
[session]
timeout_secs = 3600
max_sessions_per_user = 100
default_isolation_level = "READ_COMMITTED"  # Lowest overhead
enable_stats = false  # Reduce contention
```

## Lock Manager Configuration

Controls concurrency control, deadlock detection, and lock timeouts.

### Configuration Section

```toml
[locks]
# Lock acquisition timeout in milliseconds
timeout_ms = 30000  # 30 seconds

# Deadlock detection interval in milliseconds
detection_interval_ms = 1000  # 1 second

# Enable lock statistics
enable_stats = true

# Lock table initial capacity (performance tuning)
initial_capacity = 10000
```

### Options Reference

| Option | Type | Default | Description |
|--------|------|---------|-------------|
| `timeout_ms` | Integer | `30000` | Maximum time to wait for lock |
| `detection_interval_ms` | Integer | `1000` | How often to check for deadlocks |
| `enable_stats` | Boolean | `true` | Track lock acquisition stats |
| `initial_capacity` | Integer | `10000` | Initial hash table size for locks |

### Examples

**Low-latency (aggressive timeouts):**

```toml
[locks]
timeout_ms = 5000  # 5 seconds
detection_interval_ms = 500  # 500ms
```

**Long-running transactions:**

```toml
[locks]
timeout_ms = 300000  # 5 minutes
detection_interval_ms = 5000  # 5 seconds
```

**High-concurrency workload:**

```toml
[locks]
timeout_ms = 10000
detection_interval_ms = 1000
initial_capacity = 100000  # Large lock table
enable_stats = false  # Reduce overhead
```

## Dump Configuration

Controls automated backup, dump scheduling, and retention policies.

### Configuration Section

```toml
[dump]
# Enable automatic dumps on the schedule below
auto_dump_enabled = false

# Cron schedule for automatic dumps (empty = none), e.g. "0 */6 * * *"
schedule = ""

# Compression: "zstd", "gzip" or "none"
compression = "zstd"

# Roll over to a new dump file after this size (MB)
max_dump_size_mb = 10000

# Number of old dumps to keep (0 = keep all)
keep_dumps = 10

# Directory for automatic dumps
dump_dir = ".dumps"
```

### Options Reference

| Option | Type | Default | Description |
|--------|------|---------|-------------|
| `auto_dump_enabled` | Boolean | `false` | Enable scheduled automatic dumps |
| `schedule` | String | `""` | Cron expression for automatic dumps |
| `compression` | String | `"zstd"` | `zstd`, `gzip` or `none` |
| `max_dump_size_mb` | Integer | `10000` | Maximum size of one dump file before rolling |
| `keep_dumps` | Integer | `10` | Old dumps to keep (`0` = all) |
| `dump_dir` | String | `".dumps"` | Directory for automatic dumps |

There is no compression-level, WAL-size-trigger or batch-size setting. The
`start --dump-schedule "<cron>"` flag sets the schedule from the command line.

### Cron Schedule Examples

| Expression | Meaning |
|------------|---------|
| `"0 */6 * * *"` | Every 6 hours |
| `"0 2 * * *"` | Daily at 2 AM |
| `"0 2 * * 0"` | Weekly on Sunday at 2 AM |
| `"0 0 1 * *"` | Monthly on 1st at midnight |
| `"*/15 * * * *"` | Every 15 minutes |

### Examples

**Daily backups (production):**

```toml
[dump]
auto_dump_enabled = true
schedule = "0 2 * * *"  # 2 AM daily
compression = "zstd"
dump_dir = "/var/backups/heliosdb/daily"
keep_dumps = 90
```

**Disabled (manual dumps only):**

```toml
[dump]
auto_dump_enabled = false
```

## Resource Quotas Configuration

Controls per-user resource limits and system-wide constraints.

### Configuration Section

```toml
[resource_quotas]
# Per-user memory limit (bytes, 0 = unlimited)
memory_limit_per_user = 1073741824  # 1GB

# Per-user connection limit
connection_limit_per_user = 10

# Per-transaction timeout (seconds, 0 = unlimited)
transaction_timeout_secs = 300  # 5 minutes

# Query execution timeout (seconds, 0 = unlimited)
query_timeout_secs = 60  # 1 minute

# System-wide memory limit (bytes, 0 = unlimited)
system_memory_limit = 8589934592  # 8GB

# Maximum total connections (all users)
max_total_connections = 100
```

### Options Reference

| Option | Type | Default | Description |
|--------|------|---------|-------------|
| `memory_limit_per_user` | Integer | `1073741824` | Per-user memory limit (bytes) |
| `connection_limit_per_user` | Integer | `10` | Max connections per user |
| `transaction_timeout_secs` | Integer | `300` | Transaction timeout |
| `query_timeout_secs` | Integer | `60` | Query execution timeout |
| `system_memory_limit` | Integer | `8589934592` | System-wide memory limit |
| `max_total_connections` | Integer | `100` | Total connection limit |

### Examples

**Development (unlimited):**

```toml
[resource_quotas]
memory_limit_per_user = 0  # Unlimited
connection_limit_per_user = 0
transaction_timeout_secs = 0
query_timeout_secs = 0
```

**Production (strict limits):**

```toml
[resource_quotas]
memory_limit_per_user = 536870912  # 512MB
connection_limit_per_user = 5
transaction_timeout_secs = 60  # 1 minute
query_timeout_secs = 30  # 30 seconds
system_memory_limit = 4294967296  # 4GB total
max_total_connections = 50
```

**High-concurrency (balanced):**

```toml
[resource_quotas]
memory_limit_per_user = 268435456  # 256MB
connection_limit_per_user = 20
transaction_timeout_secs = 120
query_timeout_secs = 60
max_total_connections = 500
```

## Server Configuration

Controls network server settings and connection handling.

### Configuration Section

```toml
[server]
# Listen port
port = 5432

# Bind address (127.0.0.1 = localhost, 0.0.0.0 = all interfaces)
listen = "127.0.0.1"

# Maximum concurrent connections
max_connections = 100

# Connection timeout (seconds)
connection_timeout_secs = 30

# TCP keepalive interval (seconds, 0 = disabled)
keepalive_interval_secs = 60

# Enable TCP_NODELAY (disable Nagle's algorithm)
tcp_nodelay = true
```

### Options Reference

| Option | Type | Default | Description |
|--------|------|---------|-------------|
| `port` | Integer | `5432` | TCP listen port |
| `listen` | String | `"127.0.0.1"` | Bind address |
| `max_connections` | Integer | `100` | Maximum concurrent connections |
| `connection_timeout_secs` | Integer | `30` | Connection timeout |
| `keepalive_interval_secs` | Integer | `60` | TCP keepalive interval |
| `tcp_nodelay` | Boolean | `true` | Disable Nagle's algorithm |

### Examples

**Development (localhost only):**

```toml
[server]
port = 5432
listen = "127.0.0.1"
max_connections = 10
```

**Production (public access):**

```toml
[server]
port = 5432
listen = "0.0.0.0"
max_connections = 200
connection_timeout_secs = 60
keepalive_interval_secs = 30
tcp_nodelay = true
```

**Load-balanced (high availability):**

```toml
[server]
port = 5432
listen = "0.0.0.0"
max_connections = 500
connection_timeout_secs = 10
keepalive_interval_secs = 15
tcp_nodelay = true
```

## Authentication Configuration

Controls user authentication and authorization.

### Configuration Section

```toml
[auth]
# Authentication method: "trust", "password", "scram-sha-256"
method = "password"

# Password hashing algorithm: "argon2", "bcrypt"
password_hash = "argon2"

# Argon2 parameters (if password_hash = "argon2")
argon2_memory_kb = 4096
argon2_iterations = 3
argon2_parallelism = 1

# User definitions (development only - use external auth in production)
[[auth.users]]
username = "admin"
password_hash = "$argon2id$v=19$m=4096,t=3,p=1$..."
roles = ["admin", "read", "write"]

[[auth.users]]
username = "readonly"
password_hash = "$argon2id$v=19$m=4096,t=3,p=1$..."
roles = ["read"]
```

### Options Reference

| Option | Type | Default | Description |
|--------|------|---------|-------------|
| `method` | String | `"password"` | Authentication method |
| `password_hash` | String | `"argon2"` | Password hashing algorithm |
| `argon2_memory_kb` | Integer | `4096` | Argon2 memory cost |
| `argon2_iterations` | Integer | `3` | Argon2 time cost |
| `argon2_parallelism` | Integer | `1` | Argon2 parallelism |

### Authentication Methods

| Method | Security | Use Case |
|--------|----------|----------|
| `trust` | None | Development only |
| `password` | Medium | Internal networks |
| `scram-sha-256` | High | Production environments |

### Generating Password Hashes

```bash
# Using heliosdb-nano
heliosdb-nano hash-password

# Prompt:
# Enter password: ********
# Password hash: $argon2id$v=19$m=4096,t=3,p=1$...

# Or via command line
echo -n "mypassword" | heliosdb-nano hash-password --stdin
```

### Examples

**Development (trust):**

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

**Production (SCRAM-SHA-256):**

```toml
[auth]
method = "scram-sha-256"
password_hash = "argon2"
argon2_memory_kb = 65536  # 64MB for high security
argon2_iterations = 5
```

## Logging Configuration

Controls logging output, levels, and formats.

### Configuration Section

```toml
[logging]
# Log level: "error", "warn", "info", "debug", "trace"
level = "info"

# Log format: "text", "json"
format = "text"

# Log output: "stdout", "stderr", "file"
output = "stdout"

# Log file path (if output = "file")
file_path = "/var/log/heliosdb/heliosdb.log"

# Enable log rotation
rotate = true

# Max log file size (bytes)
max_size = 104857600  # 100MB

# Number of old log files to keep
max_backups = 10
```

### Options Reference

| Option | Type | Default | Description |
|--------|------|---------|-------------|
| `level` | String | `"info"` | Logging level |
| `format` | String | `"text"` | Log format |
| `output` | String | `"stdout"` | Log destination |
| `file_path` | String | `"/var/log/heliosdb/heliosdb.log"` | Log file path |
| `rotate` | Boolean | `true` | Enable log rotation |
| `max_size` | Integer | `104857600` | Max log file size |
| `max_backups` | Integer | `10` | Old log files to keep |

### Examples

**Development (verbose):**

```toml
[logging]
level = "debug"
format = "text"
output = "stdout"
```

**Production (structured):**

```toml
[logging]
level = "info"
format = "json"
output = "file"
file_path = "/var/log/heliosdb/heliosdb.log"
rotate = true
max_size = 104857600  # 100MB
max_backups = 30
```

**High-volume (minimal):**

```toml
[logging]
level = "warn"  # Only warnings and errors
format = "json"
output = "file"
file_path = "/var/log/heliosdb/heliosdb.log"
rotate = true
max_size = 524288000  # 500MB
max_backups = 5
```

## Complete Configuration Example

**operationally hardened configuration:**

```toml
# config.toml - HeliosDB Nano

[server]
port = 5432
listen = "0.0.0.0"
max_connections = 200
connection_timeout_secs = 60
keepalive_interval_secs = 30
tcp_nodelay = true

[session]
timeout_secs = 1800  # 30 minutes
max_sessions_per_user = 10
default_isolation_level = "READ_COMMITTED"
enable_stats = true
cleanup_interval_secs = 300

[locks]
timeout_ms = 30000  # 30 seconds
detection_interval_ms = 1000
enable_stats = true
initial_capacity = 10000

[dump]
auto_dump_enabled = true
schedule = "0 2 * * *"  # Daily at 2 AM
compression = "zstd"
dump_dir = "/var/backups/heliosdb"
keep_dumps = 30

[resource_quotas]
memory_limit_per_user = 1073741824  # 1GB
connection_limit_per_user = 10
transaction_timeout_secs = 300  # 5 minutes
query_timeout_secs = 60  # 1 minute
system_memory_limit = 8589934592  # 8GB
max_total_connections = 200

[auth]
method = "scram-sha-256"
password_hash = "argon2"
argon2_memory_kb = 8192
argon2_iterations = 3
argon2_parallelism = 1

[[auth.users]]
username = "admin"
password_hash = "$argon2id$v=19$m=8192,t=3,p=1$..."
roles = ["admin"]

[logging]
level = "info"
format = "json"
output = "file"
file_path = "/var/log/heliosdb/heliosdb.log"
rotate = true
max_size = 104857600
max_backups = 30
```

## Default Values Table

| Section | Option | Default | Type |
|---------|--------|---------|------|
| **session** | timeout_secs | 3600 | Integer |
| | max_sessions_per_user | 10 | Integer |
| | default_isolation_level | "READ_COMMITTED" | String |
| | enable_stats | true | Boolean |
| | cleanup_interval_secs | 300 | Integer |
| **locks** | timeout_ms | 30000 | Integer |
| | detection_interval_ms | 1000 | Integer |
| | enable_stats | true | Boolean |
| | initial_capacity | 10000 | Integer |
| **dump** | auto_dump_enabled | false | Boolean |
| | schedule | "" | String |
| | compression | "zstd" | String |
| | max_dump_size_mb | 10000 | Integer |
| | keep_dumps | 10 | Integer |
| | dump_dir | ".dumps" | String |
| **resource_quotas** | memory_limit_per_user | 1073741824 | Integer |
| | connection_limit_per_user | 10 | Integer |
| | transaction_timeout_secs | 300 | Integer |
| | query_timeout_secs | 60 | Integer |
| | system_memory_limit | 8589934592 | Integer |
| | max_total_connections | 100 | Integer |
| **server** | port | 5432 | Integer |
| | listen | "127.0.0.1" | String |
| | max_connections | 100 | Integer |
| | connection_timeout_secs | 30 | Integer |
| | keepalive_interval_secs | 60 | Integer |
| | tcp_nodelay | true | Boolean |
| **auth** | method | "password" | String |
| | password_hash | "argon2" | String |
| | argon2_memory_kb | 4096 | Integer |
| | argon2_iterations | 3 | Integer |
| | argon2_parallelism | 1 | Integer |
| **logging** | level | "info" | String |
| | format | "text" | String |
| | output | "stdout" | String |
| | rotate | true | Boolean |
| | max_size | 104857600 | Integer |
| | max_backups | 10 | Integer |

## Tuning Recommendations

### Development Environment

```toml
[session]
timeout_secs = 28800  # 8 hours
max_sessions_per_user = 50

[locks]
timeout_ms = 60000  # 1 minute (long debugging sessions)

[resource_quotas]
memory_limit_per_user = 0  # Unlimited
transaction_timeout_secs = 0

[auth]
method = "trust"  # No auth

[logging]
level = "debug"
format = "text"
```

### Production Environment

```toml
[session]
timeout_secs = 1800  # 30 minutes
max_sessions_per_user = 5

[locks]
timeout_ms = 10000  # 10 seconds

[resource_quotas]
memory_limit_per_user = 536870912  # 512MB
transaction_timeout_secs = 120

[auth]
method = "scram-sha-256"

[logging]
level = "info"
format = "json"
output = "file"
```

### High-Concurrency Environment

```toml
[session]
max_sessions_per_user = 100
default_isolation_level = "READ_COMMITTED"  # Lowest overhead

[locks]
timeout_ms = 5000  # Aggressive
initial_capacity = 100000  # Large lock table

[resource_quotas]
memory_limit_per_user = 268435456  # 256MB
max_total_connections = 500

[server]
max_connections = 500
tcp_nodelay = true
```

## Security Considerations

### 1. Authentication

```toml
# ✗ NEVER use in production
[auth]
method = "trust"

# ✓ Always use strong authentication
[auth]
method = "scram-sha-256"
password_hash = "argon2"
argon2_memory_kb = 65536  # High cost
argon2_iterations = 5
```

### 2. Network Binding

```toml
# ✗ Avoid exposing to public internet
[server]
listen = "0.0.0.0"  # All interfaces

# ✓ Bind to localhost or specific IP
[server]
listen = "127.0.0.1"  # Localhost only
# OR
listen = "10.0.1.50"  # Specific internal IP
```

### 3. Resource Limits

```toml
# ✓ Always set resource limits in production
[resource_quotas]
memory_limit_per_user = 1073741824
connection_limit_per_user = 10
transaction_timeout_secs = 300
query_timeout_secs = 60
```

### 4. Logging

```toml
# ✓ Enable structured logging for security monitoring
[logging]
level = "info"
format = "json"  # Machine-readable for SIEM
output = "file"
```

## Performance Tuning Tips

### 1. Lock Contention

```toml
# Reduce lock timeout for high-throughput
[locks]
timeout_ms = 5000  # Fail fast
detection_interval_ms = 500
```

### 2. Memory Usage

```toml
# For large datasets, increase memory limits
[resource_quotas]
memory_limit_per_user = 2147483648  # 2GB
system_memory_limit = 17179869184  # 16GB
```

### 3. Connection Pooling

```toml
# Increase connection limits for connection pools
[server]
max_connections = 500

[resource_quotas]
connection_limit_per_user = 50
max_total_connections = 500
```

### 4. Dump Performance

```toml
# Skip compression for the fastest dumps (larger files)
[dump]
compression = "none"
```

### 5. Session Management

```toml
# Reduce overhead with longer cleanup intervals
[session]
cleanup_interval_secs = 600  # 10 minutes
enable_stats = false  # Disable if not monitoring
```

---

## See Also

- [CLI Reference](https://www.heliosdb.com/docs/nano/reference/cli_reference/) - Command-line interface
- [In-Memory Mode Guide](https://www.heliosdb.com/docs/nano/guides/user/inmemory_mode/) - In-memory operations
- [Dump/Restore Guide](https://www.heliosdb.com/docs/nano/guides/user/dump_restore/) - Backup procedures
- [Security Hardening Guide](https://www.heliosdb.com/docs/nano/guides/security_hardening/) - Security best practices