Skip to main content
Version: v2.x

GraphQL Engine server config reference

Introduction​

Every GraphQL engine command is structured as:

$ graphql-engine <server-flags> serve <command-flags>

The flags can be passed as environment variables as well.

graphql-engine command flags / environment variables​

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

Flag and ENV VariableDetails

Flag:

--database-url <DB_URL>

ENV variable:

HASURA_GRAPHQL_DATABASE_URL

Postgres database URL:

postgres://<user>:<password>@<host>:<port>/<db-name>

Example:

postgres://admin:mypass@mydomain.com:5432/mydb

Flag:

--metadata-database-url <METADATA-DATABASE-URL>

ENV variable:

HASURA_GRAPHQL_METADATA_DATABASE_URL

Postgres database URL that will be used to store the Hasura metadata. By default the database configured using HASURA_GRAPHQL_DATABASE_URL will be used to store the metadata.

Postgres database URL:

postgres://<user>:<password>@<host>:<port>/<db-name>

Example:

postgres://admin:mypass@mydomain.com:5432/metadata_db

(Available for versions > v2.0.0)

Or you can specify the following options (only via flags):

    --host                      Postgres server host
-p, --port                      Postgres server port
-u, --user                      Database user name
-p, --password                  Password of the user
-d, --dbname                    Database name to connect to
-o, --pg-connection-options     PostgreSQL connection options
Note

The default configuration of PostgreSQL 11 and older may result in loss of precision when retrieving IEEE 754 style data, such as float4, real or double precision values, from the database. To avoid this, set the extra_float_digits PostgreSQL connection parameter to 3. This can be done by passing '--pg-connection-options=-c extra_float_digits=3' to graphql-engine, or by passing this option as part of the database url:

postgres://admin:mypass@mydomain.com:5432/mydb?options=-c%20extra_float_digits%3D3

serve sub-command flags / environment variables​

For the serve sub-command the table below contains the available flags and environment variables. For those available only on Hasura EE, reference this table at the bottom of the page.

Flag and ENV VariableDetails

Flag:

--admin-internal-errors <true|false>

ENV variable:

HASURA_GRAPHQL_ADMIN_INTERNAL_ERRORS

Enables including 'internal' information in an error response for requests made by an 'admin' (default: true)

(Available for versions > v1.2.0)

Flag:

--admin-secret <ADMIN_SECRET_KEY>

ENV variable:

HASURA_GRAPHQL_ADMIN_SECRET

Admin secret key, required to access this instance. This is mandatory when you use webhook or JWT.

Flag:

--async-actions-fetch-interval

ENV variable:

HASURA_GRAPHQL_ASYNC_ACTIONS_FETCH_INTERVAL

Interval in milliseconds to sleep before trying to fetch async actions again after a fetch returned no async actions from metadata storage. Value 0 implies completely disable fetching async actions from the storage.

(Available for versions > v2.0.0)

Flag:

--auth-hook <WEBHOOK_URL>

ENV variable:

HASURA_GRAPHQL_AUTH_HOOK

URL of the authorization webhook required to authorize requests. See auth webhooks docs for more details.

Flag:

--auth-hook-mode <GET|POST>

ENV variable:

HASURA_GRAPHQL_AUTH_HOOK_MODE

HTTP method to use for the authorization webhook. (default: GET)

Flag:

-c, --connections <NO_OF_CONNS>

ENV variable:

HASURA_GRAPHQL_PG_CONNECTIONS

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

(Deprecated in versions > v2.0.0. See details)

Flag:

--conn-lifetime <SECONDS>

ENV variable:

HASURA_GRAPHQL_PG_CONN_LIFETIME

Time from connection creation after which the connection should be destroyed and a new one created. A value of 0 indicates we should never destroy an active connection. If 0 is passed, memory from large query results may not be reclaimed. (default: 600 sec)

(Deprecated in versions > v2.0.0. See details)

Flag:

--console-assets-dir

ENV variable:

HASURA_GRAPHQL_CONSOLE_ASSETS_DIR

Set the value to /srv/console-assets for the console to load assets from the server itself instead of CDN.

Flag:

--cors-domain <DOMAINS>

ENV variable:

HASURA_GRAPHQL_CORS_DOMAIN

CSV of list of domains, including scheme (http/https) and port, to allow for CORS. Wildcard domains are allowed. (See Configure CORS)

Flag:

--metadata-database-extensions-schema

ENV variable:

HASURA_GRAPHQL_METADATA_DATABASE_EXTENSIONS_SCHEMA

The schema in which Hasura can install extensions in the metadata database. Default: public.

Flag:

--dev-mode

ENV variable:

HASURA_GRAPHQL_DEV_MODE

Set dev mode for GraphQL requests; include the internal key in the errors extensions of the response (if required).

(Available for versions > v1.2.0)

Flag:

--disable-cors

ENV variable:

HASURA_GRAPHQL_DISABLE_CORS

Disable CORS. Do not send any CORS headers on any request.

Flag:

--enable-allowlist

ENV variable:

HASURA_GRAPHQL_ENABLE_ALLOWLIST

Restrict queries allowed to be executed by the GraphQL engine to those that are part of the configured allow-list. Default: false

Flag:

--enable-console <true|false>

ENV variable:

HASURA_GRAPHQL_ENABLE_CONSOLE

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

Flag:

--enable-log-compression <true|false>

ENV variable:

HASURA_GRAPHQL_ENABLE_LOG_COMPRESSION

Enable sending compressed logs to metrics server.

Flag:

--enable-maintenance-mode

ENV variable:

HASURA_GRAPHQL_ENABLE_MAINTENANCE_MODE

Disable updating of metadata on the server. (default: false)

(Available for versions > v2.0.0)

Flag:

--enable-metadata-query-logging

ENV variable:

HASURA_GRAPHQL_ENABLE_METADATA_QUERY_LOGGING

Enables the query field in http-logs for metadata queries. (default: false)

Flag:

--enable-remote-schema-permissions

ENV variable:

HASURA_GRAPHQL_ENABLE_REMOTE_SCHEMA_PERMISSIONS

Enable remote schema permissions. (default: false)

(Available for versions > v2.0.0)

Flag:

--enable-telemetry <true|false>

ENV variable:

HASURA_GRAPHQL_ENABLE_TELEMETRY

Enable anonymous telemetry. (default: true)

Flag:

--enabled-apis <APIS>

ENV variable:

HASURA_GRAPHQL_ENABLED_APIS

Comma separated list of APIs (options: metadata, graphql, pgdump, config) to be enabled. (default: metadata, graphql, pgdump, config)

Flag:

--enabled-log-types

ENV variable:

HASURA_GRAPHQL_ENABLED_LOG_TYPES

Set the enabled log types. This is a comma-separated list of log-types to enable. Default: startup, http-log, webhook-log, websocket-log. See log types for more details.

Flag:

--events-http-pool-size

ENV variable:

HASURA_GRAPHQL_EVENTS_HTTP_POOL_SIZE

Max event processing threads. (default: 100)

Flag:

--events-fetch-batch-size

ENV variable:

HASURA_GRAPHQL_EVENTS_FETCH_BATCH_SIZE

Maximum number of events to be fetched from the DB in a single batch. (default: 100)

(Available for versions > v2.0.0)

Flag:

--events-fetch-interval

ENV variable:

HASURA_GRAPHQL_EVENTS_FETCH_INTERVAL

Interval in milliseconds to sleep before trying to fetch events again after a fetch returned no events from postgres.

Flag:

--experimental-features

ENV variable:

HASURA_GRAPHQL_EXPERIMENTAL_FEATURES

List of experimental features to be enabled. A comma separated value is expected. Options: inherited_roles, optimise_permission_filters, naming_convention, streaming_subscriptions, apollo_federation, hide_update_many_fields, bigquery_string_numeric_input, hide_aggregation_predicates, hide_stream_fields.

(Available for versions > v2.0.0)

Flag:

--graceful-shutdown-timeout

ENV variable:

HASURA_GRAPHQL_GRACEFUL_SHUTDOWN_TIMEOUT

Timeout (in seconds) to wait for the in-flight events (event triggers and scheduled triggers) and async actions to complete before the server shuts down completely (default: 60 sec). If the in-flight events are not completed within the timeout, those events are marked as pending.

(Available for versions > v2.0.0)

Flag:

-i, --tx-iso <TXISO>

ENV variable:

HASURA_GRAPHQL_TX_ISOLATION

Transaction isolation. read-committed / repeatable-read / serializable (default: read-committed)

(Deprecated in versions > v2.0.0. See details)

Flag:

--infer-function-permissions

ENV variable:

HASURA_GRAPHQL_INFER_FUNCTION_PERMISSIONS

When the --infer-function-permissions flag 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 the --infer-function-permissions flag is set to true or the flag is omitted (defaults to true), the permission of the function is inferred from the select permissions from the target table of the function, only for stable/immutable functions. Volatile functions are not exposed to any of the roles in this case.

(Available for versions > v2.0.0)

Flag:

--jwt-secret <JSON_CONFIG>

ENV variable:

HASURA_GRAPHQL_JWT_SECRET

A JSON string containing type and the JWK used for verifying (and other optional details). Example: {"type": "HS256", "key": "3bd561c37d214b4496d09049fadc542c"}. See the JWT docs for more details.

Flag:

--live-queries-multiplexed-batch-size

ENV variable:

HASURA_GRAPHQL_LIVE_QUERIES_MULTIPLEXED_BATCH_SIZE

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

Flag:

--live-queries-multiplexed-refetch-interval

ENV variable:

HASURA_GRAPHQL_LIVE_QUERIES_MULTIPLEXED_REFETCH_INTERVAL

Updated results (if any) will be sent at most once in this interval (in milliseconds) for live queries which can be multiplexed. Default: 1000 (1 sec)

Flag:

--log-level

ENV variable:

HASURA_GRAPHQL_LOG_LEVEL

Set the logging level. Default: info. Options: debug, info, warn, error.

Flag:

--pool-timeout

ENV variable:

HASURA_GRAPHQL_POOL_TIMEOUT

How long to wait when acquiring a Postgres connection, in seconds. (default: forever)

Flag:

--query-plan-cache-size

ENV variable:

HASURA_GRAPHQL_QUERY_PLAN_CACHE_SIZE

The maximum number of query plans that can be cached, allowed values: 0-65535, 0 disables the cache. (Default: 4000)

(Deprecated in versions > v2.0.0. See details)

Flag:

--retries <NO_OF_RETRIES>

ENV variable:

HASURA_GRAPHQL_NO_OF_RETRIES

Number of retries if Postgres connection error occurs. (default: 1)

(Deprecated in versions > v2.0.0. See details)

Flag:

-s, --stripes <NO_OF_STRIPES>

ENV variable:

HASURA_GRAPHQL_PG_STRIPES

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

(Deprecated in versions > v2.0.0. See details)

Flag:

--schema-sync-poll-interval

ENV variable:

HASURA_GRAPHQL_SCHEMA_SYNC_POLL_INTERVAL

Interval to poll metadata storage for updates in milliseconds. Default: 1000 (1 sec). Set to 0 to disable.

(Available for versions > v2.0.0)

Flag:

--server-host <HOST>

ENV variable:

HASURA_GRAPHQL_SERVER_HOST

Host on which graphql-engine will listen (default: *)

Flag:

--server-port <PORT>

ENV variable:

HASURA_GRAPHQL_SERVER_PORT

Port on which graphql-engine should be served (default: 8080)

Flag:

--streaming-queries-multiplexed-batch-size

ENV variable:

HASURA_GRAPHQL_STREAMING_QUERIES_MULTIPLEXED_BATCH_SIZE

Multiplexed streaming queries are split into batches of the specified size. (Default: 100)

Flag:

--streaming-queries-multiplexed-refetch-interval

ENV variable:

HASURA_GRAPHQL_STREAMING_QUERIES_MULTIPLEXED_REFETCH_INTERVAL

Updated results (if any) will be sent at most once in this interval (in milliseconds) for streaming queries which can be multiplexed. (Default: 1000)

Flag:​

--stringify-numeric-types

ENV variable:

HASURA_GRAPHQL_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. (default: false)

Flag:

--timeout <SECONDS>

ENV variable:

HASURA_GRAPHQL_PG_TIMEOUT

Each connection's idle time before it is closed (default: 180 sec)

(Deprecated in versions > v2.0.0. See details)

Flag:

--unauthorized-role <ROLE>

ENV variable:

HASURA_GRAPHQL_UNAUTHORIZED_ROLE

Unauthorized role, used when access-key is not sent in access-key only mode or the Authorization header is absent in JWT mode. Example: anonymous. Now whenever the "authorization" header is absent, the request's role will default to anonymous.

Flag:

--use-prepared-statements <true|false>

ENV variable:

HASURA_GRAPHQL_USE_PREPARED_STATEMENTS

Use prepared statements for queries. (default: true)

(Deprecated in versions > v2.0.0. See details)

Flag:

--websocket-compression

ENV variable:

HASURA_GRAPHQL_CONNECTION_COMPRESSION

Enable WebSocket permessage-deflate compression. (default: false)

(Available for versions > v2.0.0)

Flag:

--websocket-connection-init-timeout <SECONDS>

ENV variable:

HASURA_GRAPHQL_WEBSOCKET_CONNECTION_INIT_TIMEOUT

Used to set the connection initialisation timeout for graphql-ws clients. This is ignored for subscription-transport-ws (Apollo) clients. (default: 3)

Flag:

--websocket-keepalive <SECONDS>

ENV variable:

HASURA_GRAPHQL_WEBSOCKET_KEEPALIVE

Used to set the Keep Alive delay for client that use the subscription-transport-ws (Apollo) protocol. For graphql-ws clients the graphql-engine sends PING messages instead. (default: 5)

(Available for versions > v2.0.0)

Flag:

--ws-read-cookie <true|false>

ENV variable:

HASURA_GRAPHQL_WS_READ_COOKIE

Read cookie on WebSocket initial handshake even when CORS is disabled. This can be a potential security flaw! Please make sure you know what you're doing. This configuration is only applicable when CORS is disabled. (default: false)

Flag:

N/A

ENV variable:

HASURA_GRAPHQL_EVENTS_HTTP_POOL_SIZE

Maximum number of concurrent http workers delivering events at any time. (default: 100)

Flag:

N/A

ENV variable:

HASURA_GRAPHQL_EVENTS_FETCH_INTERVAL

Interval in milliseconds to sleep before trying to fetch events again after a fetch returned no events from postgres. (default: 1000)

Flag:

--v1-boolean-null-collapse

ENV variable:

HASURA_GRAPHQL_V1_BOOLEAN_NULL_COLLAPSE

Evaluate null values in where input object to True instead of error.

Flag:

N/A

ENV variable:

HASURA_GRAPHQL_DEFAULT_NAMING_CONVENTION

Used to set the default naming convention for all sources. See naming convention for more information.

(default: hasura-default)

(Available for versions ≥ v2.8.0)
Note

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

Hasura EE sub-command flags / environment variables​

The following serve sub-commands are available only on Hasura EE.

Flag and ENV VariableDetails

Flag:

--admin-secrets

ENV variable:

HASURA_GRAPHQL_ADMIN_SECRETS

A list of valid admin secret keys.

Flag:

--connections-per-read-replica <NO OF CONNS PER READ REPLICA>

ENV variable:

HASURA_GRAPHQL_CONNECTIONS_PER_READ_REPLICA

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

Flag:

--jwt-secrets

ENV variable:

HASURA_GRAPHQL_JWT_SECRETS

A JSON array of objects containing type and the JWK used for verifying. e.g:

[{\"type\": \"HS256\", \"key\": \"<your-hmac-shared-secret>\", \"claims_namespace\": \"<optional-custom-claims-key-name>\"}, {\"type\": \"RS256\", \"issuer\": \"my-issuer\", \"key\": \"<your-PEM-RSA-public-key>\", \"claims_namespace\": \"<optional-custom-claims-key-name>\"}]

Flag:

--max-cache-size

ENV variable:

HASURA_GRAPHQL_MAX_CACHE_SIZE

Maximum cache size in MB. (Default: 1 MB)

Flag:

--pg-ssl-certificate-path <DIRECTORY>

ENV variable:

HASURA_GRAPHQL_PG_SSL_CERTIFICATE_PATH

Path for storage of postgres SSL certificates when set via environment variable reference.

Flag:

--pro-endpoint <HASURA PRO ENDPOINT>

ENV variable:

HASURA_GRAPHQL_PRO_ENDPOINT

The pro endpoint for authorization and collect metrics.

Flag:

--pro-key <HASURA PRO KEY>

ENV variable:

HASURA_GRAPHQL_PRO_KEY

The pro key that you have received.

Flag:

--rate-limit-redis-tls-hostname <HOSTNAME>

ENV variable:

HASURA_GRAPHQL_RATE_LIMIT_REDIS_TLS_HOSTNAME

Hostname to use for SNI when connecting to rate-limiting Redis instance over TLS.

Flag:

--rate-limit-redis-url <URL>

ENV variable:

HASURA_GRAPHQL_RATE_LIMIT_REDIS_URL

Redis URL in the form redis://username:password@host:port/db to use for rate limiting.

Flag:

--rate-limit-redis-use-tls <true|false>

ENV variable:

HASURA_GRAPHQL_RATE_LIMIT_REDIS_USE_TLS

Whether or not to use TLS to connect to caching Redis instance.

Flag:

--read-replica-url <READ REPLICA URL>

ENV variable:

HASURA_GRAPHQL_READ_REPLICA_URL

URL for a read replica of the database.

Flag:

--redis-tls-hostname <HOSTNAME>

ENV variable:

HASURA_GRAPHQL_REDIS_TLS_HOSTNAME

Hostname to use for SNI when connecting to caching Redis instance over TLS.

Flag:

--redis-tls-shared-ca-store-path <PATH TO SHARED CA STORE>

ENV variable:

HASURA_GRAPHQL_REDIS_TLS_SHARED_CA_STORE_PATH

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

Flag:

--redis-url <URL>

ENV variable:

HASURA_GRAPHQL_REDIS_URL

Redis URL in the form redis://username:password@host:port/db to use for query caching.

Flag:

--stripes-per-read-replica

ENV variable:

HASURA_GRAPHQL_STRIPES_PER_READ_REPLICA

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

(Deprecated in versions > v2.0.0. See details)

Hasura ConHasura Con
The Hasura User Conference
New Product Announcements
View Recordings

Start with GraphQL on Hasura for Free

  • Build apps and APIs 10x faster
  • Built-in authorization and caching
  • 8x more performant than hand-rolled APIs
Try GraphQL with Hasura
Promo