athena_rs 2.12.1

Database gateway API
Documentation

Athena RS 2.8.1

current version: 2.12.1

Table of Contents

Overview

Athena is a lightweight database gateway that proxies and executes queries across Athena/ScyllaDB, PostgreSQL, and Supabase backends. The Actix-powered API normalizes headers, shapes JSON payloads, and exposes helper utilities so API consumers, dashboards, and embedded tooling all speak the same surface.

Key features:

  • Gateway surface: /gateway/fetch, /gateway/update, /gateway/insert, /gateway/delete, and /gateway/query accept structured payloads, route via X-Athena-Client, and normalize camelCase / snake_case when configured.
  • Online client catalog: x-athena-client resolution now supports both legacy config.yaml entries and database-backed client rows stored in the athena_logging database, with a local in-memory registry for hot-path performance.
  • Post-processing: Fetch/update responses honor optional group_by, time_granularity, aggregation_column, aggregation_strategy, and aggregation_dedup. When those fields are present, the response includes a post_processing.grouped array with labels, rows, and aggregation metadata.
  • SQL executor: /query/sql reroutes raw SQL to Athena/Scylla, PostgreSQL pools (SQLx), or Supabase while sharing the same X-Athena-Client routing registry.
  • Proxy helpers: proxy_request forwards arbitrary REST calls with auth header management and caching helpers in api::cache.
  • Cache layer: Built on moka with optional Redis write-through and TTL management.
  • Admin control plane: /admin/clients* manages client creation, editing, freeze/unfreeze, removal, and aggregated client statistics traced from the existing gateway log tables; /admin/provision and /admin/backups* handle schema bootstrap plus S3-based backups/restores.
  • Configuration: config.yaml still bootstraps the server, logging/auth clients, Redis caching, and the camel-to-snake toggle; download the synced HTTP spec via GET /openapi.yaml and the WebSocket contract via GET /openapi-wss.yaml (covers /wss/gateway, /wss/info, /health, and /ready for the Bun proxy) so you can import both into OpenAPI tooling.

Quickstart

Prerequisites

  • Rust 1.85+
  • Docker (optional, for local Postgres/Redis)

1) Configure

  • Update config.yaml
  • Set your Postgres URIs with environment variables

Example local logging DB:

  • POSTGRES_ATHENA_LOGGING_URI=postgres://athena:athena@localhost:5433/athena_logging

2) Run

cargo run -- --api-only

3) Use

  • Send X-Athena-Client on gateway requests
  • Use apikey for protected endpoints

Core Endpoints

Gateway

  • POST /gateway/fetch
  • PUT /gateway/insert
  • POST /gateway/update
  • DELETE /gateway/delete
  • POST /gateway/query

Deferred Queue

  • GET /gateway/deferred/{request_id}
  • POST /gateway/deferred/{request_id}/requeue

Health and Specs

  • GET /
  • GET /ping
  • GET /health
  • GET /metrics
  • GET /openapi.yaml
  • GET /openapi-wss.yaml

Minimal Request Examples

Deferred query

POST /gateway/query
X-Athena-Client: reporting
X-Athena-Defer: true
Content-Type: application/json

{
  "query": "SELECT now()"
}

Check deferred status

GET /gateway/deferred/REQUEST_ID

Requeue failed or completed job

POST /gateway/deferred/REQUEST_ID/requeue

Config Essentials

In config.yaml, focus on:

  • api.port
  • postgres_clients
  • gateway settings for admission/defer/worker
  • logging/auth client names

Useful gateway knobs:

  • gateway.admission_limit_enabled
  • gateway.admission_global_requests_per_window
  • gateway.admission_per_client_requests_per_window
  • gateway.admission_window_secs
  • gateway.admission_defer_on_limit_enabled
  • gateway.admission_defer_route_prefixes
  • gateway.deferred_query_worker_enabled
  • gateway.deferred_query_worker_poll_ms

Operational Alerts

Use these Prometheus rules as a baseline:

groups:
  - name: athena-deferred-queue
    rules:
      - alert: AthenaDeferredQueueBacklogGrowing
        expr: athena_gateway_deferred_queue_requests{status="queued"} > 200
        for: 5m
        labels:
          severity: warning
        annotations:
          summary: "Athena deferred queue backlog is high"
          description: "Queued deferred requests stayed above 200 for 5 minutes."

      - alert: AthenaDeferredQueueStuckOldest
        expr: athena_gateway_deferred_queue_oldest_age_seconds > 300
        for: 10m
        labels:
          severity: critical
        annotations:
          summary: "Athena deferred queue appears stuck"
          description: "Oldest queued/running deferred request age exceeded 5 minutes."

      - alert: AthenaDeferredQueueStorageDown
        expr: athena_gateway_deferred_queue_storage_up == 0
        for: 2m
        labels:
          severity: critical
        annotations:
          summary: "Athena deferred queue storage unavailable"
          description: "Logging Postgres is unreachable for deferred queue reads."

      - alert: AthenaDeferredQueryFailuresBurst
        expr: increase(athena_gateway_deferred_events_total{kind="gateway_query",status="failed"}[10m]) > 10
        for: 0m
        labels:
          severity: warning
        annotations:
          summary: "Athena deferred query failures are spiking"
          description: "More than 10 deferred query jobs failed in the last 10 minutes."

Common Commands

API Keys

Athena persists API keys in the api_keys family of tables. The master record is api_keys, which stores public_id, name, description, an optional client_name, and the salt/hash for the secret. Columns like api_keys_id, created_at, and updated_at are generated in the database, and api_keys_id is the UUID returned to callers while the internal bigint id backs foreign keys. api_key_rights names the allowed capability strings, api_key_right_grants bridges keys to rights, api_key_config keeps global enforcement, api_key_client_config holds per-client overrides, and api_key_auth_log records every authentication attempt (request metadata, presented hash, granted rights, failure reason, etc.).

All of the /admin/* surfaces and the protected /schema/clients + /clients endpoints require the static admin key stored in the ATHENA_KEY_12 environment variable. Provide that key through Authorization: Bearer <key>, apikey, x-api-key, x-athena-key, or the ?api_key= query string when invoking these routes.

When you hit POST /admin/api-keys, Athena generates a public_id, secrets (salt/hash), and returns the plaintext credential as ath_{public}.{secret}. Capture the secret at creation time; it cannot be retrieved later. Rights can be assigned at creation or updated later by supplying the rights array.

Admin API key routes

  • GET /admin/api-keys – list all API key records plus granted rights.
  • POST /admin/api-keys – create a new API key by providing name, optional description, optional client_name, optional expires_at timestamp, and optional rights.
  • PATCH /admin/api-keys/{id} – adjust an existing key (name, description, client, expiry, active flag, rights).
  • DELETE /admin/api-keys/{id} – archive the key.
  • GET /admin/api-key-rights – list every right string that can be granted.
  • POST /admin/api-key-rights – create a new right (name + optional description).
  • PATCH /admin/api-key-rights/{id} – rename/describe a right.
  • DELETE /admin/api-key-rights/{id} – remove a right (cascades via api_key_right_grants).
  • GET /admin/api-key-config – read the global enforcement setting plus the client overrides.
  • PUT /admin/api-key-config – flip the global enforce_api_keys flag.
  • GET /admin/api-key-clients – list the per-client overrides.
  • PUT /admin/api-key-clients/{client_name} – upsert a per-client override.
  • DELETE /admin/api-key-clients/{client_name} – remove a client override and fall back to the global setting.

Client Catalog Admin Routes

Athena stores scalable client definitions in the athena_clients table inside the athena_logging database. Each row can reference either a direct pg_uri or a pg_uri_env_var, and bootstrap will also seed config-only clients into the table so old installs migrate forward without duplicate entries.

  • GET /admin/clients – list the database catalog plus the current runtime registry snapshot.
  • POST /admin/clients – create a database-managed client by sending client_name and either pg_uri or pg_uri_env_var.
  • PATCH /admin/clients/{client_name} – update connection settings, description, or active state.
  • PUT /admin/clients/{client_name}/freeze – freeze or unfreeze a client without deleting its catalog row.
  • DELETE /admin/clients/{client_name} – soft-delete a client from the database catalog and remove it from the runtime registry.
  • GET /admin/clients/statistics – list aggregated request and operation counts per client.
  • POST /admin/clients/statistics/refresh – rebuild client_statistics and client_table_statistics from the existing log tables.
  • GET /admin/clients/{client_name}/statistics – inspect totals plus per-table operation counts for one client.
  • GET /admin/clients/{client_name}/statistics/drilldown – list gateway_operation_log rows for a given table_name and operation (query params status, limit, offset).

Frozen or deleted database rows are removed from the hot-path registry, so request handlers keep using local memory instead of querying the catalog table for every call.

Every admin response is described in openapi.yaml, so use that spec if you need payload samples, response codes, or schema definitions.

Success example:

{
  "status": "success",
  "message": "Fetched 10 rows",
  "data": {"rows": [...]}
}

Error example:

{
  "status": "error",
  "message": "Invalid request",
  "error": "Missing table_name"
}

CLI Tools

Rust CLI

The athena_rs binary exposes CLI helpers alongside the HTTP API. Global flags apply to every subcommand:

  • --config / --config-path <PATH> override config.yaml (default: config.yaml). The same path may be set with ATHENA_CONFIG_PATH (CLI wins if both are set).
  • --pipelines <PATH> overrides the default pipeline definitions file (config/pipelines.yaml).
  • --port <PORT> overrides the API port when booting the server.
  • --api-only boots the server (same as server).

Configuration load order (searched in this order and logged when missing):

  1. %APPDATA%/athena
  2. %LOCALAPPDATA%/athena
  3. %USERPROFILE%/.athena
  4. $XDG_CONFIG_HOME/athena
  5. $HOME/.config/athena
  6. $HOME/.athena
  7. ~/Library/Application Support/athena (macOS)
  8. Current working directory

If no config file is found, Athena copies the bundled config.yaml into the first writable directory before loading it. Errors list every inspected location so you can troubleshoot missing configs.

Commands:

  • server (or --api-only): start the Actix Web server. Respect --port, --config, and --pipelines overrides.
  • pipeline: run an inline pipeline with --client <NAME>, --payload-json, --payload-file, and --pipeline <NAME> to reference prebuilt definitions.
  • clients subcommands (list, add, remove, set-default): mutate config/clients.json that stores reusable Postgres connection names.
  • fetch: proxy a gateway fetch request to https://athena-db.com/gateway/fetch (or the URL supplied via --url). Use --client to pick a saved client and --body-json / --body-file to supply the payload.
  • diag: print OS, architecture, CPU count, Rust version, hostname, and locale metadata.
  • version: show the build version (cargo run -- --version works too).

Systemd: see scripts/athena.service. Set ATHENA_CONFIG_PATH in EnvironmentFile (for example .env) or pass --config <ABSOLUTE_PATH> in ExecStart.

TypeScript CLI

The CLI in cli/ generates SQL/CQL artifacts from Supabase schema metadata.

Installation:

cargo build --release

Test

cargo test --verbose

Lint and format

cargo fmt --check

cargo clippy --all-targets --all-features

API only server

cargo run -- --api-only

Web and CLI

  • Web explorer: apps/web
  • TypeScript CLI: cli

Notes

  • If a client is missing or offline, Athena keeps running with available clients.
  • For custom Supabase routing, include x-supabase-url and x-supabase-key headers.
  • OpenAPI contracts are served directly from the API process.