Configuration Options

Athena’s runtime configuration comes from four layers:

1. config.yaml file sections such as api, gateway, backup, and postgres_clients
2. Environment variables used directly by the runtime or interpolated into config.yaml
3. Validation ranges inside config.yaml that clamp numeric values to safe ranges
4. CLI flags such as --config, --pipelines, --port, and --api-only

This page is meant to be exhaustive for the main Athena server and the runtime settings wired through src/config.rs and src/config_validation.rs.

Config file discovery and precedence

Athena searches for config.yaml in this order:

1. %APPDATA%/athena/config.yaml
2. %LOCALAPPDATA%/athena/config.yaml
3. %USERPROFILE%/.athena/config.yaml
4. $XDG_CONFIG_HOME/athena/config.yaml
5. $HOME/.config/athena/config.yaml
6. $HOME/.athena/config.yaml
7. ~/Library/Application Support/athena/config.yaml on macOS
8. ./config.yaml in the current working directory

If no file exists, Athena copies the bundled default config into the first writable location.

Explicit overrides

Top-level config.yaml sections

urls, hosts, and authenticator

urls

urls is a list of single-entry maps. Each key is a logical service name and each value is the resolved URL or an env placeholder.

Example:

urls:
	- athena: "${ATHENA_DB_URL}"

hosts

hosts works the same way, but stores named host strings used by the application.

Example:

hosts:
	- athena: athena-db.com
	- scylladb: "${SCYLLADB_HOST}"

authenticator

authenticator stores per-service credential objects.

Example:

authenticator:
	- scylladb:
			username: "${SCYLLADB_USERNAME}"
			password: "${SCYLLADB_PASSWORD}"

postgres_clients

postgres_clients defines the logical Postgres pools Athena will try to create at boot.

Example:

postgres_clients:
	- athena_logging: "${POSTGRES_ATHENA_LOGGING_URI}"
	- athena_benchmark: "${POSTGRES_ATHENA_BENCHMARK_URI}"

Behavior notes

• Failed Postgres clients log warnings and are skipped; startup continues with healthy clients.
• gateway.logging_pg_uri can override the URI used for the configured logging client.
• Catalog-backed clients from athena_clients can extend the registry after bootstrap when enabled.

api section reference

API env helpers

gateway section reference

Routing and shaping

Direct JDBC routing and safety

Read resilience

Admission limiting and deferred queue

Insert windowing and batching

Client catalog and startup stats

backup section reference

backup stores S3-compatible backup defaults. In practice, most deployments use env vars directly.

Backup and restore env vars

validation_ranges reference

validation_ranges lets the config file define numeric min/max clamps for both file-based config values and runtime environment variables.

validation_ranges.config

These keys clamp values read from config.yaml:

• api.port
• api.cache_ttl
• api.pool_idle_timeout
• api.keep_alive_secs
• api.client_disconnect_timeout_secs
• api.client_request_timeout_secs
• api.http_workers
• api.http_max_connections
• api.http_backlog
• api.tcp_keepalive_secs
• gateway.insert_execution_window_ms
• gateway.insert_window_max_batch
• gateway.insert_window_max_queued
• gateway.resilience_timeout_secs
• gateway.resilience_read_max_retries
• gateway.resilience_initial_backoff_ms
• gateway.admission_global_requests_per_window
• gateway.admission_per_client_requests_per_window
• gateway.admission_window_secs
• gateway.deferred_query_worker_poll_ms

validation_ranges.env

These keys clamp runtime env settings loaded through RuntimeEnvSettings.

Runtime env settings (src/config_validation.rs)

These settings do not live under api or gateway in config.yaml; they are direct environment variables with internal defaults and optional min/max clamps.

Other important environment variables

These are widely used operational variables that are not part of RuntimeEnvSettings but matter in most Athena deployments.

Operational guidance

Shared logging pool

If gateway.logging_client and gateway.auth_client point to the same logical client, auth, request logs, operation logs, deferred queue rows, admission events, and aggregate stats can all compete for one Postgres pool. For deep dives, read:

• docs/architecture_gateway_pool_starvation.md
• docs/architecture_gateway_client_stats_batcher.md

Startup behavior

• Missing or unreachable Postgres clients do not hard-stop the process; Athena starts with the reachable subset.
• Config-backed clients and database-backed catalog clients merge into one in-memory registry.
• Numeric values can be silently clamped to configured validation_ranges limits; watch logs for normalization warnings.

Safe authoring tips

• Prefer env placeholders for secrets: "${POSTGRES_ATHENA_LOGGING_URI}"
• Keep gateway.logging_client, gateway.auth_client, and gateway.benchmark_client explicit in production
• Use validation_ranges when you want guardrails for operators editing config by hand