GraphQL Engine Server Configuration Reference

Introduction

This page details which flags and environment variables are available to customize a Hasura GraphQL Engine instance. For details on how to implement flags or environment variables, check out this page.

GraphQL Engine command flags and environment variables

For the graphql-engine command, these are the available flags and environment variables:

Database URL

This connection string can be used to connect Hasura to a PostgreSQL data source which Hasura will automatically add to the list of connected data sources.

:::info Note

This config option is supported to maintain backwards compatibility with v1.x Hasura instances. In versions v2.0 and above, databases can be connected using any custom environment variables of your choice. Our docker-compose.yaml files in the install manifests reference PG_DATABASE_URL as the environment variable to use for connecting to a database, but this can be any plaintext value which does not start with HASURA_.

:::

Metadata Database URL

This Postgres database URL is used to store Hasura's Metadata. This can also be a URI of the form dynamic-from-file:///path/to/file, where the referenced file contains a postgres connection string, which will be read dynamically every time a new connection is established. This allows the server to be used in an environment where secrets are rotated frequently.

:::info Note

THe metadata database URL needs to be set for Hasura to start.

:::

Serve sub-command flags and environment variables {#command-flags}

For the serve sub-command, these are the available flags and environment variables:

:::info Note

When the equivalent flags for environment variables are used, the flags will take precedence.

:::

Admin Internal Errors

Internal information is included in an error response for requests made by an admin.

Admin Secret Key

A secret key required to access the Hasura instance.

:::info Note

When you use webhook or JWT mode for authentication, setting this value is mandatory.

:::

Admin Secrets

A list of valid admin secret keys any one of which can be used to access the Hasura instance.

:::info Note

If both Admin Secret and Admin Secrets are set, then only Admin Secrets will be used.

:::

Async Actions Fetch Batch Size

The maximum number of async actions to be processed in a single batch.

Async Actions Fetch Interval

The interval, in milliseconds, to sleep before trying to fetch async actions again after a fetch returned no async actions from metadata storage. A value of 0 implies completely disabling fetching async actions from the storage.

Auth Hook

The URL required to authorize requests when utilizing authentication webhooks.

:::info Note

Having an admin secret set is mandatory for setting this value.

:::

Auth Hook Mode

If you're using a webhook for authentication, The HTTP method used by Hasura to make requests.

Send Request Body to Auth Hook

Whether or not to send the request body (graphql request/variables) to the auth hook in POST mode.

BigQuery String Numeric Input

Stringify certain BigQuery numeric types, specifically bignumeric, float64, int64, numeric and aliases thereof, as they don't fit into the IEEE 754 spec for JSON encoding-decoding.

Cache Max Entry TTL

The maximum Query Cache TTL value in seconds, defaulting to 3600 seconds (1 hour).

Close WebSocket connections on metadata change

When metadata changes, close all WebSocket connections (with error code 1012). This is useful when you want to ensure that all clients reconnect to the latest metadata.

Configured Header Precedence

Whether the metadata configured headers are given higher precedence than client headers for Actions and postgres input validations.

Connections per Read-Replica

The maximum number of Postgres connections per read-replica that can be opened per stripe. When the maximum is reached we will block until a new connection becomes available, even if there is capacity in other stripes.

Console Assets Directory

By default, Console assets are loaded from a CDN. For the Console to load assets from the server itself instead of the CDN, set the value to /srv/console-assets.

CORS Domain

List of domains, including scheme (http/https) and port, to allow for CORS.
Wildcard domains are allowed, but there are important limitations:

1. Wildcard for subdomains:

   • Wildcards (*) can indicate only a single subdomain position and must be the starting subdomain.
     • Example: http://*.foo.com will match http://app.foo.com but not http://www.app.foo.com.
     • Similarly, http://www.*.foo.com will not handle http://www.app.foo.com.
   • To allow multiple subdomains, you need to explicitly list entries for each required subdomain.
     • Example: Use http://*.app.foo.com and http://*.app2.foo.com for http://bar.app.foo.com and http://baz.app2.foo.com.

2. Wildcard for ports is not supported:

   • Ports must be specified explicitly.
     • Example: Use http://localhost:3000 instead of http://localhost:*.

Setting an empty value will block requests from all other domains.

:::info Note

Because the Console on Hasura Cloud runs on the 'cloud.hasura.io' domain, Hasura Cloud automatically adds it as an allowed CORS domain. Setting an empty value will block requests from all other domains.

:::

Dev Mode

Sets dev mode for GraphQL requests, i.e. in case of errors, includes an internal key in the errors extensions of the response.

Default Naming Convention

Used to set the default naming convention for all sources.

Disable CORS

Disables CORS. Hasura will not send any CORS headers on any request.

Disable Native Query validation

Disable validation of Native Queries against the database.

Dynamic Secrets Allowed Path Prefix

Enables the ability to source Postgres connection strings from files on disk using DynamicFromFile, and the ability for Template Variables to use the contents of files in Data Connector configuration transforms. File paths used with these features must start with the prefix set in this environment variable.

Enable Allow List

Restrict requests allowed to be executed by the GraphQL Engine to those that are part of the configured Allow List.

Enable Apollo Federation

Enables the Apollo Federation feature. This allows Hasura to be connected as a subgraph in an Apollo supergraph.

Enable Automated Persisted Queries

Enables the Automated Persisted Queries feature.

Set Automated Persisted Queries TTL

Sets the query TTL in the cache store for Automated Persisted Queries.

Enable Error Log Level for Trigger Errors

Sets the log-level as error for Trigger type error logs (Event Triggers, Scheduled Triggers, Cron Triggers).

Enable Console

Enable the Hasura Console (served by the server on / and /console).

Enable High-cardinality Labels for Metrics

Enable high-cardinality labels for Prometheus Metrics. Enabling this setting will add more labels to some of the metrics (e.g. operation_name label for Graphql subscription metrics).

The list of affected metrics are:

Enable Log Compression

Enable sending compressed logs to metrics server.

Enable Maintenance Mode

Enabling maintenance mode disables updating of Metadata on the server.

Enable Metadata Query Logging

Enabling this setting includes the query field in http-logs for Metadata queries.

Enable Remote Schema Permissions

Enable RBAC for Remote Schemas

Enable Relay

Enable the Relay API endpoint (/v1/relay and /v1beta1/relay). When disabled, requests to the relay endpoint return an error with instructions to enable it. Disabling this reduces memory usage for deployments that do not use Relay.

Enable Telemetry

Setting this enables or disables anonymous telemetry.

Enabled APIs

List of APIs to be enabled on a Hasura GraphQL Engine instance.

Enabled Log Types

The options below represent log types on the Community Edition. Enterprise-specific log types - and descriptions of all log types — can be found here.

Events HTTP Pool Size

Maximum number of concurrent HTTP workers for event delivery.

Events Fetch Batch Size

The maximum number of events to be fetched from the DB in a single batch.

Events Fetch Interval

The interval, in milliseconds, to sleep before trying to fetch events again after a fetch returned no events from Postgres. Setting this value to 0 will stop event trigger processing.

Experimental Features

List of experimental features to be enabled.

Header Size Limit

Sets the maximum cumulative length of all headers in bytes.

Graceful Shutdown Timeout

The timeout, expressed in seconds, to wait for in-flight events (such as Event Triggers and Scheduled Triggers) and async actions to complete before the server shuts down completely. If the in-flight events are not completed within the timeout, those events are marked as pending.

Infer Function Permissions

When this is set to false, a function f, stable, immutable or volatile is only exposed for a role r if there is a permission defined on the function f for the role r, creating a function permission will only be allowed if there is a select permission on the table type.

When this is set to true or is omitted, the permission of the function is inferred from the select permissions from the target table of the function, only for stable or immutable functions. Volatile functions are not exposed to any of the roles in this case. See the permissions for custom functions docs for more details.

JWT Secret

The JWT Secret variable is set equal to a JSON string containing a type property set equal to the method of encryption and the JWK (key) used for verifying a JWT. See the JWT docs for more details.

:::info Note

Having an admin secret set is mandatory for setting this value.

:::

JWT Secrets

List of JWT secrets to authenticate with different JWT issuers.

:::info Note

If both JWT Secret and JWT Secrets are set, then JWT Secrets will be used.

:::

Live Queries Multiplexed Refetch Interval

When utilizing live queries, updated results - if any - will be sent, at most, once during this interval - measured in milliseconds - for any live queries which can be multiplexed.

Log Level

This variable sets the level for Hasura's logs.

Max Cache Size

The maximum cache size, measured in MB, for queries.

Metadata Database Extension Schema

The schema in which Hasura can install extensions in the Metadata database.

Multiplexed Batch Size

Multiplexed live queries are split into batches of the specified size.

Null in Non-nullable Variables

GraphQL query validation is fixed in v2.36.0-beta.1, where queries that assigned a null value to variables with non-nullable type were allowed.

Example:

query ($user_id: Int!) {
  users(where: { id: { _eq: $user_id } }) {
    id
    name
  }
}

variables

{
  "user_id": null
}

To rollback to the old behavior, i.e., allow null value for non-nullable variables, use this option.

Number of Retries

:::warning Notice

Deprecated in versions > v2.0.0: see details.

:::

The number of retries if a Postgres connection error occurs.

Number of Stripes

:::warning Notice

Deprecated in versions > v2.0.0: see details.

:::

The number of stripes (distinct sub-pools) to maintain with Postgres. New connections will be taken from a particular stripe pseudo-randomly.

PG Connections

:::warning Notice

Deprecated in versions > v2.0.0: see details.

:::

The maximum number of Postgres connections that can be opened per stripe. When the maximum is reached we will block connections until a new connection becomes available, even if there is capacity in other stripes.

PG Connection Lifetime

:::warning Notice

In versions > v2.0.0 this affects only connections to the postgres database used for the metadata catalog. The equivalent setting for data sources is now connection_info > pool_settings > connection_lifetime in the metadata.

:::

Time from connection creation, in seconds, after which the connection should be destroyed and a new one created. A value of 0 indicates Hasura should never destroy an active connection. If 0 is passed, memory from large query results may not be reclaimed.

Pool Timeout

:::warning Notice

Deprecated in versions > v2.0.0: see details.

:::

Pool Timeout determines, in seconds, how long to wait when acquiring a Postgres connection.

Postgres SSL Certificate Path

The path for storage of Postgres SSL certificates when set via environment variable reference.

Postgres Timeout

:::warning Notice

Deprecated in versions > v2.0.0: see details.

:::

Each connection's idle time, measured in seconds, before it's closed.

Preserve 401 Errors

Preserves HTTP 401 (Unauthorized) status codes from webhook auth responses and JWT auth failures. By default, all GraphQL errors are returned with HTTP status code 200, even authentication errors. When enabled, 401 errors will be propagated back to the client.

Query Plan Cache Size

:::warning Notice

Deprecated in versions > v2.0.0: see details.

:::

The maximum number of query plans that can be cached, where 0 disables the cache.

Rate-Limit Redis TLS Hostname

The hostname to use for SNI when connecting to a rate-limiting Redis instance over TLS.

Rate-Limit Redis URL

The Redis URL to use for rate limiting.

Rate-Limit Redis Use TLS

Whether to use TLS to connect to a caching Redis instance.

Read Replica URL

The URL for a read replica of the database.

:::warning Notice

Deprecated in versions > v2.0.0: see details.

:::

Redis Timeout

The timeout for redis queries while serving requests. The timeout is in seconds.

Redis no-fail on Startup

Whether to proceed if redis is unavailable at engine startup. If set to true and there are issues with redis on startup then the server will start as though caching and rate limiting were disabled until the next engine restart. A startup log message will be displayed in this case mentioning "redis operation failed".

Redis TLS Hostname

The hostname to use for SNI when connecting to a caching Redis instance over TLS.

Redis TLS Shared CA Store Path

The path to a shared CA store to use to connect to both (caching and rate-limiting) Redis URLs over TLS.

Caching Redis Pool Size

Maximum number of connections in the caching Redis connection pool. For high-traffic production environments, you may want to increase this value. For development or low-traffic environments, you can decrease it to conserve resources.

Rate Limit Redis Pool Size

Maximum number of connections in the rate-limiting Redis connection pool. For high-traffic production environments with heavy rate-limiting usage, you may want to increase this value. For development or low-traffic environments, you can decrease it to conserve resources.

Redis URL

The Redis URL to use for query caching and Webhook Auth Caching.

Remote Schema prioritize data

Setting this will prioritize data or errors if both fields are present in the Remote Schema response.

Schema Sync Poll Interval

The interval, in milliseconds, to poll Metadata storage for updates. To disable, set this value to 0.

Server Host

The host on which graphql-engine will listen. The default is *.

Server Port

The port on which graphql-engine should be served.

Single Sign-on Providers

List of third-party identity providers to enable Single Sign-on authentication for the console.

Skip Arguments with null Values for Remote Schema

Skip arguments with null values while resolving fields from Remote Schemas. For instance:

query RemoteQuery {
  users(type:null) {
    id
    ...
  }
}

is forwarded as:

query RemoteQuery {
  users {
    id
    ...
  }
}

Streaming Queries Multiplexed Batch Size

Multiplexed streaming queries are split into batches of the specified size.

Streaming Queries Multiplexed Refetch Interval

For streaming queries which can be multiplexed, updated results - if any - will be sent, at most, once during this interval.

Stringify Numeric Types

Stringify certain Postgres numeric types, specifically bigint ,numeric ,decimal and double precision as they don't fit into the IEEE-754 spec for JSON encoding-decoding.

Stripes per Read Replica

:::warning Notice

Deprecated in versions > v2.0.0: see details.

:::

The number of stripes (connection pools) to maintain per read replica.

Transaction Isolation

:::warning Notice

Deprecated in versions > v2.0.0: see details.

:::

This sets transaction isolation.

Trace SQL and GraphQL Queries

Add SQL and GraphQL queries to the OTLP traces.

Unauthorized Role

This identifies an unauthorized role, used when the x-hasura-admin-key is not sent or the Authorization header is absent in JWT mode.

Use Prepared Statements

:::warning Notice

Deprecated in versions > v2.0.0: see details.

:::

Whether to use prepared statements for queries.

v1 Boolean Null Collapse

Evaluate null values in where input object to True instead of error. Learn more in our upgrade guide.

Websocket Compression

Enable WebSocket permessage-deflate compression.

Websocket Connection Init Timeout

Used to set the connection initialization timeout for GraphQL subscription protocols (graphql-transport-ws and subscriptions-transport-ws).

Websocket Queue Size

Sets the maximum number of messages buffered per WebSocket connection before older messages are dropped to make room for newer ones. The primary purpose is to bound memory usage when a subscriber is slow to consume messages — without a limit, a stalled or slow client can cause unbounded memory growth on the server as subscription results accumulate.

When the queue is full, the oldest undelivered message is evicted and the newest message takes its place. The hasura_websocket_messages_evicted_total Prometheus metric counts these evictions; pairing it with hasura_websocket_messages_queued_total gives the eviction rate as a fraction of total sends.

Interaction with poll interval: A slow subscriber is most likely to overflow the queue when the subscription poll interval is short relative to the client's consumption rate. If you lower HASURA_GRAPHQL_LIVE_QUERIES_MULTIPLEXED_REFETCH_INTERVAL, consider whether clients can keep up, and tune this queue size accordingly.

Setting the queue size to 1 means a subscriber always receives the most recently computed result and never holds stale intermediate values in memory. This is safe for live query subscriptions, where the guarantee is only eventual consistency with the current database state — missing intermediate values is by design.

Streaming subscriptions: Overflow has a stronger impact here. Streaming queries present results as an ordered sequence of elements and rely on cursor-based pagination to make progress; a dropped message means a gap in that sequence that cannot be recovered. Use a larger queue size (or increase the poll interval) if streaming query clients may be slow consumers. Streaming subscriptions require the streaming_subscriptions experimental feature flag.

Websocket Keepalive

Used to set the Keep Alive delay for clients that use the subscriptions-transport-ws (Apollo) protocol. For graphql-ws clients, the graphql-engine sends PING messages instead.

WS Read Cookie

Read cookie on WebSocket initial handshake even when CORS is disabled. This can be a potential security flaw! This configuration is only applicable when CORS is disabled.

Masked request variables in query-log

Sets a list of variable names to be masked in query logs.