Routing Model

Primary Routing Header

Athena resolves target clients using:

X-Athena-Client (logical client name)

This selects the logical Athena client for gateway, query, and many admin operations. The long-term contract is that Athena resolves a client definition first, then resolves the backend beneath it.

See Athena Contracts for the full resolver and dispatch contract.

Optional Direct Routing Inputs

x-pg-uri (preferred): direct PostgreSQL routing
x-athena-jdbc-url (compatibility)
x-jdbc-url / X-JDBC-URL (compatibility)
x-supabase-url + x-supabase-key: custom Supabase request routing

For direct PostgreSQL headers, Athena uses one canonical parser and normalizes JDBC URLs (jdbc:postgresql://...) to PostgreSQL URI form.

Direct PostgreSQL header precedence

When more than one direct PostgreSQL header is present, Athena applies:

x-pg-uri
x-athena-jdbc-url
x-jdbc-url / X-JDBC-URL

All three feed the same parser and PostgreSQL-target validator.

Direct URI Credentials and Auth

For PostgreSQL gateway routes and PostgreSQL driver SQL routes:

x-pg-uri can replace X-Athena-Client.
If the URI contains both username and password, Athena can accept the request without X-Athena-Key.
Non-PostgreSQL SQL drivers (athena/scylla, supabase) still follow standard auth requirements.

For complete route coverage and examples, see Direct PostgreSQL Routing (x-pg-uri).

Resolution order (simplified)

If direct PostgreSQL URI headers are present, resolve and validate direct URI target.
Otherwise resolve by X-Athena-Client.
If wildcard host routing is enabled and no direct header is present, host inference may provide the client context.

Wildcard Host Routing

With wildcard routing enabled, Athena can infer client context from request hostnames.

Example pattern:

*.v3.athena-cluster.com

When active, route metadata maps host labels to internal client names.

Wildcard host inference is skipped whenever a direct PostgreSQL URI header (x-pg-uri, x-athena-jdbc-url, or x-jdbc-url) is present.

See Tenant Wildcard Hostnames for the canonical tenant-host onboarding flow and the PostgreSQL public-host metadata boundary.

Public Route Dispatch

Athena also supports curated public operations:

POST /public/{route_key}/{op}

Route keys map to controlled backend operations for external consumers.