Configuration Options

Athena’s runtime configuration comes from four layers:

1. config.yaml file sections such as api, gateway, backup, daemon, 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 the deprecated --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

Scalar keys under sections such as api, gateway, backup, daemon, and typesense can also be overridden with ATHENA_<SECTION>_<KEY> style environment variables, for example ATHENA_API_PORT or ATHENA_DAEMON_ENABLED.

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 PostgreSQL URI routing safety (gateway.jdbc_*)

These controls apply to direct PostgreSQL routing headers:

• x-pg-uri (preferred)
• x-athena-jdbc-url (compatibility)
• x-jdbc-url / X-JDBC-URL (compatibility)

Behavior notes:

• Headers are normalized through one parser before host policy checks.
• Keyless direct bypass still requires URI username + password credentials.
• Host allow/deny policy is independent from auth bypass eligibility.

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 worker defaults and bounds

• backup.worker_enabled: default true
• backup.execution_worker_poll_ms: default 1500, minimum 250
• backup.schedule_worker_poll_ms: default 30000, minimum 1000
• backup.worker_max_attempts: default 3, clamped to 1..=10
• backup.worker_lease_ttl_minutes: default 15, clamped to 1..=120

Backup and restore env vars

daemon section reference

daemon controls whether Athena keeps worker ownership inside athena_rs or moves it into the separate daemon package.

Daemon behavior notes

• daemon.enabled: false means athena_rs still owns legacy, deferred, backup, and Typesense workers inline.
• daemon.enabled: true means those worker families must be started outside the API process, normally with athena_daemon.
• Clone jobs never execute inside athena_rs; they require athena_daemon or athena_clone_worker.
• athena_clone_worker is the only supported partial split today. Backup, deferred, Typesense, and legacy workers do not yet have a per-family "external only, inline off" toggle.

Daemon environment overrides

The generic config override pattern still applies, so ATHENA_DAEMON_ENABLED and ATHENA_DAEMON_CLONE_WORKER_ENABLED can override their matching config.yaml keys. The dedicated daemon package also reads a runtime-specific set of overrides:

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