Configuration

Database

Schema Reloading

Authentication

Server

Limits

Compatibility

Hasura Authentication

GraphQL Names, Permissions and Federation

Logging

Observability

Key ordering is a build-time choice

Postrust returns the keys within each object alphabetically. PostgREST returns them in the order of the select list. That difference is decided when the binary is compiled rather than at run time, because it depends on the map type holding a JSON object, so PGRST_COMPAT_MODE cannot switch it on. It is a Cargo feature:

cargo build --release -p postrust-server --features compat-key-order

# Default build
curl 'localhost:3000/api/users?select=status,name,id&limit=1'
# -> [{"id":1,"name":"Alice","status":"active"}]

# With compat-key-order
curl 'localhost:3000/api/users?select=status,name,id&limit=1'
# -> [{"status":"active","name":"Alice","id":1}]

It is off by default because it is not free. Measured by running both builds as containers against the same database and alternating between them, a three-column response cost 1% and an eight-column response 15%: for objects this small a few short string comparisons beat hashing every key, so the sorted map is genuinely the faster one. Turn it on when byte-level compatibility matters more.

Running with PGRST_COMPAT_MODE=true on a binary built without the feature logs a warning at startup, so the difference is not left to be found by diffing responses.

Hasura authentication

The GraphQL surface reads Hasura’s headers, so a deployment migrating from Hasura keeps sending what it already sends. Both spellings of each variable are read, so an existing HASURA_GRAPHQL_* environment needs no renaming.

Set the secret, and a caller that holds it is an administrator — and an administrator may ask to be treated as someone else:

curl localhost:3000/v1/graphql \
  -H 'X-Hasura-Admin-Secret: shh' \
  -H 'X-Hasura-Role: user' \
  -H 'X-Hasura-User-Id: 1' \
  -d '{"query":"{ article { id title } }"}'

That request is answered as user, and x-hasura-user-id becomes a session variable a row-level policy reads as current_setting('hasura.user_id') — or that a function taking hasura_session json receives whole. A Hasura role is not a database role: Artist and anonymous need not exist in any catalogue.

Choosing a role with a token

A token that allows more than one identity carries x-hasura-default-role — who the caller is when it asks for nothing — beside x-hasura-allowed-roles, the list it may ask for instead. The asking is done with an X-Hasura-Role header, and no admin secret is needed for it. That list sits inside the signature, so a caller may choose among the identities it was issued and cannot add one. Asking for a role the token does not list is refused. A token carrying no list allows only the role it already names.

One place this deliberately differs from Hasura

Hasura with no admin secret configured treats every caller as an administrator — which also means an unsecured deployment lets any caller name its own role and its own identity. Postrust does not: with no secret configured, x-hasura-* headers carry no weight and session variables come only from a verified token. A policy reading a value the caller chose is not a policy, and the failure is silent — the query succeeds, against the wrong rows.

See Hasura conformance for how much of the dialect this covers, measured.

Example Configuration

# Required
DATABASE_URL=postgres://user:password@localhost:5432/mydb

# Authentication
PGRST_DB_ANON_ROLE=web_anon
PGRST_JWT_SECRET=your-secret-key-at-least-32-characters

# Hasura-dialect GraphQL at /v1/graphql
PGRST_HASURA_ADMIN_SECRET=shh
PGRST_HASURA_UNAUTHORIZED_ROLE=anonymous

# Apollo Federation subgraph (optional)
# PGRST_GRAPHQL_FEDERATION=true
# PGRST_GRAPHQL_TYPE_PREFIX=billing

# Server
PGRST_SERVER_HOST=0.0.0.0
PGRST_SERVER_PORT=3000
PGRST_SERVER_CORS_ORIGINS=https://myapp.com

# Limits
PGRST_MAX_ROWS=100
PGRST_LOG_LEVEL=info

# Keys from an identity provider instead of a shared secret (optional)
# PGRST_JWT_JWKS_URL=https://<tenant>.auth0.com/.well-known/jwks.json
# PGRST_JWT_ISS=https://<tenant>.auth0.com/

# OpenTelemetry traces and metrics (optional; in the published images)
# OTEL_EXPORTER_OTLP_ENDPOINT=http://otel-collector:4318
# PGRST_LOG_FORMAT=json