neondatabase/neon

Proxy HTTP API

In addition to forwarding native libpq connections, the proxy exposes two HTTP-based query surfaces:

SQL over HTTP (POST /sql) — one-round-trip query for edge runtimes.
REST broker — JWT-authorized PostgREST-style row access (optional, gated by --features rest_broker).

The canonical user-facing documentation is proxy/README.md. This page summarizes the request/response shape and points at the implementation.

SQL over HTTP

Request

POST /sql
Host: <project>.local.neon.build:4444
Neon-Connection-String: postgresql://user:pwd@host/dbname
Content-Type: application/json

{
  "query": "SELECT $1::int[] AS arr, $2::jsonb AS obj, 42 AS num",
  "params": ["{{1,2},{3,4}}", {"key": "val", "ikey": 4242}]
}

Neon-Connection-String carries the Postgres connection string the proxy will use to talk to the actual compute on the user's behalf. It is parsed (so credentials are not URL-decoded loosely) and the host part determines project routing.

Optional headers:

Neon-Raw-Text-Output: true — return all values as text, skip type conversion.
Neon-Array-Mode: true — return rows as arrays of values rather than objects keyed by column name.

Response

{
  "command": "SELECT",
  "fields": [
    { "dataTypeID": 1007, "name": "arr" },
    { "dataTypeID": 3802, "name": "obj" },
    { "dataTypeID": 23, "name": "num" }
  ],
  "rowCount": 1,
  "rows": [
    {
      "arr": [
        [1, 2],
        [3, 4]
      ],
      "obj": { "ikey": 4242, "key": "val" },
      "num": 42
    }
  ]
}

The shape mirrors node-postgres. command is the Postgres command tag; fields lists OIDs and names; rowCount is the row count from the command tag; rows is the data.

Type mapping

proxy/README.md documents the conversion table:

Postgres int2, int4, float4, float8 → JSON number (NaN/Inf as text).
Postgres bool, null, text → JSON bool, null, string.
Postgres array → JSON array.
Postgres json, jsonb → JSON object.
Anything else → string.

Implementation

proxy/src/serverless/ is the SQL-over-HTTP implementation. Key files:

serverless/sql_over_http.rs — request parsing, response serialization.
serverless/conn_pool.rs — connection pooling per (project, role).
serverless/json.rs — Postgres → JSON type conversion.

The protocol uses Postgres's extended query protocol but with text-format response, both because not all Postgres types have binary representations and to dodge a known driver bug (sfackler/rust-postgres#1030).

REST broker

The REST broker (--is-rest-broker true, gated by Cargo feature rest_broker) exposes a PostgREST-style API on top of the same proxy infrastructure:

GET /<database>/rest/v1/<table>?select=col1,col2&col3=eq.value
Authorization: Bearer <JWT>

JWT validation uses keys configured via local_proxy.json (the same file used by the auth-broker mode). On a valid JWT, the proxy maps the HTTP request to a SQL query against the compute, which can use Row-Level Security policies tied to the JWT claims.

The implementation is in proxy/src/serverless/rest_broker.rs. Note: this depends on the subzero-core crate, which is gated behind the cargo feature flag because the production version is in a separate repo. libs/proxy/subzero_core/ is a stub used in the open-source build.

Auth broker

--is-auth-broker true is a related mode where the proxy validates JWTs and forwards the original SQL/HTTP query to a backing Postgres role determined by the JWT's role_names claim. See proxy/README.md's "auth broker setup" walkthrough.

Cancellation

A SQL-over-HTTP request that hangs can be cancelled by issuing a follow-up POST /cancel with the connection's cancellation key. Cancellation is routed across multiple proxy instances via Redis pub/sub (proxy/src/cancellation.rs).

Limits and quotas

proxy/src/rate_limiter/ enforces:

Per-source-IP request rate.
Per-project request rate.
Per-endpoint connection rate.
Maximum query size.

Limits are configurable via flags.

Testing

proxy/README.md walks through running a local proxy with a backing Postgres and Redis. The test_runner/ Python suite exercises the SQL-over-HTTP and REST broker surfaces; tests live under test_runner/regress/.