Direct PostgreSQL Routing (`x-pg-uri`)

This page is the source of truth for Athena direct PostgreSQL routing using x-pg-uri (preferred) and compatibility JDBC-style headers.

What this mode does

Direct routing lets callers target PostgreSQL without first resolving a registered Athena client name.

• Preferred header: x-pg-uri
• Compatibility headers: x-athena-jdbc-url, x-jdbc-url, X-JDBC-URL
• JDBC forms are normalized (jdbc:postgresql://... -> PostgreSQL URI form)

Header precedence and normalization

When multiple direct headers are present, Athena treats them through one canonical parser with this priority:

1. x-pg-uri
2. x-athena-jdbc-url
3. x-jdbc-url / X-JDBC-URL

Athena then validates that the resolved URI targets PostgreSQL.

Credential requirement for keyless direct routing

Keyless direct routing is only allowed when URI credentials contain both:

• username
• password

Example accepted credentialed URI:

postgres://app_user:app_password@db.example.com:5432/app_db

Example that does not qualify for keyless bypass:

postgres://db.example.com:5432/app_db

Without both credentials, normal API key auth applies.

Route coverage matrix

Auth and routing decision flow

For eligible PostgreSQL gateway routes and PostgreSQL SQL-driver requests:

1. Resolve direct URI header (preferred x-pg-uri, then compatibility headers).
2. Normalize URI input and validate PostgreSQL target format.
3. If no API key is supplied and URI has both username and password, allow direct bypass.
4. Otherwise apply normal API key enforcement rules.

This keeps non-PostgreSQL and non-gateway paths protected by default.

Operational behaviors with direct URI requests

• Wildcard host client inference is skipped when a direct PostgreSQL URI header is present.
• Deferred gateway queue execution is skipped for direct URI requests; execution is inline.
• Athena uses a deterministic opaque token for request identity (logs/cache/webhooks) so raw URI credentials are not exposed.

Request examples

Gateway fetch with keyless direct 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
  }'

Gateway query using compatibility JDBC header

curl -X POST "http://localhost:4052/gateway/query" \
  -H "content-type: application/json" \
  -H "x-athena-jdbc-url: jdbc:postgresql://db.example.com:5432/app_db?user=app_user&password=app_password" \
  -d '{
    "query": "select now() as ts"
  }'

SQL driver path (driver: postgresql) with keyless direct URI

curl -X POST "http://localhost:4052/query/sql" \
  -H "content-type: application/json" \
  -H "x-pg-uri: postgres://app_user:app_password@db.example.com:5432/app_db" \
  -d '{
    "driver": "postgresql",
    "query": "select count(*) from events",
    "db_name": "app_db"
  }'

SQL driver path (driver: supabase) still requires standard auth

curl -X POST "http://localhost:4052/query/sql" \
  -H "content-type: application/json" \
  -H "x-athena-client: analytics" \
  -H "x-athena-key: <gateway-or-admin-key>" \
  -d '{
    "driver": "supabase",
    "query": "select 1",
    "db_name": "analytics"
  }'

Troubleshooting

Related docs

• Gateway API
• Routing Model
• Security, auth ordering, and rate limits
• Security Model
• Configuration Options