athena_rs 0.77.0

WIP Database API gateway
Documentation

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 to start an Actix app that exposes the documented OpenAPI surface (openapi.yaml).
  3. Use the X-Athena-Client header to pick a Postgres pool for /gateway/* and /query/sql.

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.