Athena RS

Lightweight gateway crate that proxies Athena/Supabase/Scylla traffic and routes SQL queries through SQLx-managed PostgreSQL pools while normalizing cacheable JSON payloads.

Highlights

• Gateway endpoints: /gateway/data, /gateway/fetch, /gateway/update, and /gateway/query accept structured fetch payloads, enforce the X-Athena-Client header, and optionally normalize camelCase to snake_case when configured.
• Gateway post-processing: /gateway/data and /gateway/fetch accept optional JSON fields such as group_by, time_granularity (day, hour, minute), aggregation_column, aggregation_strategy (cumulative_sum), and aggregation_dedup. When present the response will include a post_processing.grouped array with { label, rows, aggregation } entries so callers can easily visualize grouped rows plus their (optionally deduplicated) cumulative aggregates.
• SQL executor: /query/sql dispatches to Athena/Scylla, PostgreSQL, or Supabase; PostgreSQL queries now reuse the same SQLx pool registry and honor X-Athena-Client.
• Proxy helpers: proxy_request forwards arbitrary REST calls to the configured upstream (Athena, Dexter, etc.) with caching + auth header management.
• Cache layer: Built on moka with optional Redis write-through and helper utilities in api::cache.
• Configuration: config.yaml drives URLs, caches, Postgres pools, and the camel-to-snake toggle. Use openapi.yaml for tooling compatibility.

Dedicated configuration notes

• Replace each postgres_clients URI with ${ENV_VAR_NAME} references, and provide the real host via environment variables before starting the binary; this keeps credentials out of version control and allows per-deployment secrets.

Running

1. Populate config.yaml and export the referenced env vars.
2. cargo run -- --api-only to start an Actix app that exposes the documented OpenAPI surface (openapi.yaml); the API no longer boots automatically unless --api-only or server is provided.
3. Use the X-Athena-Client header to pick a Postgres pool for /gateway/* and /query/sql.

Docker compose

1. Pre-pull the Redis image used for optional caching: docker pull redis:8.2.4-alpine3.22.
2. Run docker compose up --build to bring up the athena API and the standalone redis cache together.
3. Athena listens on http://localhost:4052 and keeps running even if Redis is turned off; caching only activates when you point ATHENA_REDIS_URL=redis://redis:6379 at the Redis service.
4. Stop the stack with docker compose down; the redis-data volume preserves cache data between runs.

CLI helpers

The same athena_rs binary now exposes CLI helpers alongside the HTTP API. Provide --config/--pipelines to override config.yaml or config/pipelines.yaml, and call cargo run -- <command> (or cargo run -- server) when you need tooling; the API only starts on boot when you pass --api-only. You can also pass --port to override the API port when booting the server instead of editing config.yaml.

• cargo run -- --api-only (or cargo run -- server) starts the Actix Web server.
• cargo run -- pipeline --client my_client --payload-file ./workflows/pipeline.json runs a pipeline request locally (use --payload-json or --payload-file to supply a source/transform/sink body and --pipeline to reference a prebuilt definition).
• cargo run -- clients list / add / remove / set-default to manage the config/clients.json file that stores reusable Postgres client names.
• cargo run -- fetch --client my_client --body-file ./examples/fetch.json posts the payload to https://athena-db.com/gateway/fetch with the saved X-Athena-Client.
• cargo run -- diag prints platform, CPU, and build metadata.
• cargo run -- --version (or cargo run -- version) prints the build version and exits.

Web explorer

• The apps/web Next.js app now hosts the Athena Explorer UI (apps/web/app/page.tsx), which renders a table list sidebar, editable datagrid, and schema action drawer powered by the gateway/SQL APIs.
• Run npm install from apps/web and start npm run dev to explore the workspace while pointing the frontend to https://athena-db.com (override via NEXT_PUBLIC_ATHENA_BASE_URL). The UI also expects the Athena headers (NEXT_PUBLIC_ATHENA_CLIENT, NEXT_PUBLIC_ATHENA_USER_ID, NEXT_PUBLIC_ATHENA_COMPANY_ID, NEXT_PUBLIC_ATHENA_ORGANIZATION_ID) when issuing insert/delete requests.
• The datagrid components now rely on the /schema/clients, /schema/tables, and /schema/columns endpoints to discover Postgres pools and table metadata while still issuing row/DDL requests through /gateway/fetch, /query/sql, and the gateway insert/delete endpoints defined in openapi.yaml. Set up postgres_clients in config.yaml so the Rust backend can expose the pools that the UI lets you switch between.

For detailed API contracts, import openapi.yaml into your preferred OpenAPI tooling.

AthenaClient SDK

The newly introduced AthenaClient SDK exposes a builder-based interface that works across Supabase, PostgreSQL, Scylla, and other backends in a single API. Use the builder to configure SSL, pools, health checks, and connection timeouts, or rely on the convenience constructors from athena_rs::AthenaClient for the most common flows.

use athena_rs::{AthenaClient, BackendType};
use serde_json::json;

let client = AthenaClient::builder()
    .backend(BackendType::Supabase)
    .url("https://project.supabase.co")
    .key("service-role-key")
    .health_tracking(true)
    .max_connections(20)
    .build()
    .await?;

let rows = client
    .select("users")
    .columns(["id", "email"])
    .where_eq("status", "active")
    .limit(10)
    .execute()
    .await?;

let _ = client
    .insert("logs")
    .payload(json!({ "message": "SDK initialized" }))
    .execute()
    .await?;

The SDK also exposes helpers such as:

• AthenaClient::new(url, key) (defaults to the native SQL backend)
• AthenaClient::new_with_backend(url, key, backend_type) for explicit backend selection
• AthenaClient::new_with_backend_name(url, key, "supabase") / "postgrest" / "scylla" / "neon" for quick scripts

Behind the scenes, AthenaClient picks the right translator (SQL vs. CQL), handles health tracking (circuit breaker + probes), and keeps the original drivers untouched, meaning your existing Supabase/SQlX/Scylla code still works while you migrate to the shared SDK.