Gateway API

Common routes

Routing modes

Gateway PostgreSQL routes support two routing approaches:

• Client routing: X-Athena-Client resolves a registered logical client/pool
• Direct PostgreSQL routing: x-pg-uri (preferred)

Compatibility direct-routing headers are also supported:

• x-athena-jdbc-url
• x-jdbc-url / X-JDBC-URL

JDBC-style values are normalized to PostgreSQL URI form before validation.

Direct URI auth behavior

For PostgreSQL-backed gateway routes (/gateway/fetch, /gateway/data, /gateway/update, /gateway/insert, /gateway/delete, /gateway/query):

• X-Athena-Client is optional when a valid direct PostgreSQL URI header is present.
• API key auth can be bypassed only when the URI includes both username and password.
• Direct URI requests execute inline; deferred queue execution is skipped.

For SQL-driver endpoints:

• /query/sql and /gateway/sql allow the same direct bypass only for driver: postgresql / driver: postgres.
• Non-PostgreSQL drivers (athena/scylla, supabase) keep normal auth rules.

Full behavior and decision matrix: Direct PostgreSQL Routing (x-pg-uri).

Schema targeting (schema_name)

Gateway now accepts optional schema_name for PostgreSQL-backed operations:

• /gateway/fetch and /gateway/data
• /gateway/insert
• /gateway/update
• /gateway/delete
• /gateway/query
• /query/sql and /gateway/sql (only when driver=postgresql)

Behavior:

• If omitted, behavior is unchanged (default search path, typically public first).
• If provided, Athena validates schema_name as a SQL identifier and executes against that schema context.
• For table-based routes, do not send both a schema-qualified table_name and schema_name in the same request.

Rejections:

• Invalid schema_name format returns 400 with message Invalid schema_name.
• Supplying both schema-qualified table_name and schema_name returns 400 (Invalid schema/table selector).
• schema_name with non-PostgreSQL SQL drivers returns 400 (Unsupported schema_name).

Fetch example (client routing)

curl -X POST "http://localhost:4052/gateway/fetch" \
  -H "content-type: application/json" \
  -H "x-athena-client: analytics" \
  -H "x-athena-key: <gateway-or-admin-key>" \
  -d '{
    "table_name": "events",
    "schema_name": "reporting",
    "columns": ["id", "type", "created_at"],
    "conditions": [{ "eq_column": "type", "eq_value": "checkout.completed" }],
    "sort_by": { "field": "created_at", "direction": "desc" },
    "limit": 100
  }'

Fetch example (direct x-pg-uri)

curl -X POST "http://localhost:4052/gateway/fetch" \
  -H "content-type: application/json" \
  -H "x-pg-uri: postgres://app_user:app_password@db.example.com:5432/app_db" \
  -d '{
    "table_name": "events",
    "conditions": [{ "eq_column": "type", "eq_value": "checkout.completed" }],
    "limit": 50
  }'

Structured select fetch

PostgreSQL-backed gateway fetch now accepts Athena's canonical nested select object as an additive request shape.

curl -X POST "http://localhost:4052/gateway/fetch" \
  -H "content-type: application/json" \
  -H "x-athena-client: analytics" \
  -H "x-athena-key: <gateway-or-admin-key>" \
  -d '{
    "table_name": "orchestral_sections",
    "select": {
      "name": true,
      "instruments": {
        "select": {
          "name": true
        },
        "where": {
          "active": { "eq": true }
        },
        "orderBy": {
          "name": "asc"
        },
        "limit": 10
      }
    },
    "orderBy": {
      "name": "asc"
    }
  }'

Use the object form as the canonical Athena contract. A compatibility select: "name,instruments(name)" string is also accepted for migration. When gateway API-key enforcement is enabled, nested structured fetches require read access to every referenced table in the tree.

Full request-shape details: Gateway Structured Select

Query example

curl -X POST "http://localhost:4052/gateway/query" \
  -H "content-type: application/json" \
  -H "x-athena-client: analytics" \
  -H "x-athena-key: <gateway-or-admin-key>" \
  -d '{
    "query":"select count(*) from events",
    "schema_name":"reporting"
  }'

Post-processing support

Fetch/update payloads may include:

• group_by
• time_granularity
• aggregation_column
• aggregation_strategy
• aggregation_dedup

When enabled, responses include post_processing.grouped.

Stats tables and typed filters

When fetching client_statistics or client_table_statistics, equality conditions on numeric and timestamp columns are aligned to Postgres column types so string JSON values do not trigger runtime type errors (42883).

See Gateway fetch and stats tables.

Structured gateway tracing

Gateway-style routes emit structured trace events on athena_rs::gateway_trace for request/response correlation:

• request_id, client, method, path, operation
• table_name, resource_id, status_code, outcome, duration_ms
• backend, cache markers, row counters, trace_id, error_code

The event shape is centralized so /gateway/*, /data, /rest/*, and /rpc/* stay aligned.