Skip to main content
Version: v2.x

GraphQL Engine Server Configuration


You can customize the configuration of the Hasura GraphQL Engine using either server flags or environment variables.

See the Server config reference for the list of all available flags and environment variables that can be configured.

Setting server configurations

Using flags

You can configure self-hosted Hasura GraphQL Engine instances by setting flags on the graphql-engine command and the serve sub-command.

The graphql-engine command

The graphql-engine command has a limited number of flags and environment variables; these pertain directly to the databases used in your project.

Every graphql-engine command is structured as:

$ graphql-engine <server-flags>

As an example, we can set the metadata database url for a project using a flag:

$ graphql-engine --metadata-database-url "postgres://<user>:<password>@<host>:<port>/<db-name>"

The serve sub-command

The serve sub-command provides opportunities to further customize Hasura's configuration.

Building on the previous example, we can set the port by which Hasura is served by pairing the serve sub-command with the --port flag and assigning a value:

$ graphql-engine --metadata-database-url "postgres://user:password@host:port/db-name" serve --port 3000

The following options can be configured via flags only:

    --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

All other flags can also be passed as environment variables.

Using environment variables

You can also use environment variables to configure the Hasura GraphQL Engine. As an example, if you're using Docker on a self-hosted instance, you can set these values by modifying your docker-compose.yaml file used to run Hasura:

# docker-compose.yaml

version: '3.6'
image: postgres:12
restart: always
- db_data:/var/lib/postgresql/data
POSTGRES_PASSWORD: postgrespassword
image: hasura/graphql-engine:v2.15.0
- '8080:8080'
- 'postgres'
restart: always
## postgres database to store Hasura metadata
HASURA_GRAPHQL_METADATA_DATABASE_URL: postgres://postgres:postgrespassword@postgres:5432/postgres
## this env var can be used to add the above postgres database to Hasura as a data source. this can be removed/updated based on your needs
PG_DATABASE_URL: postgres://postgres:postgrespassword@postgres:5432/postgres
## enable the console served by server
HASURA_GRAPHQL_ENABLE_CONSOLE: 'true' # set to "false" to disable console
## enable debugging mode. It is recommended to disable this in production
HASURA_GRAPHQL_ENABLED_LOG_TYPES: startup, http-log, webhook-log, websocket-log, query-log
## uncomment next line to run console offline (i.e load console assets from server instead of CDN)
## uncomment next line to set an admin secret

Alternatively, if you're using Hasura Cloud, you can set and add environment variables from a project's dashboard:

Setting env vars from Cloud
Flags vs. environment variables

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

Zero downtime environment variable updates

When adding or updating environment variables on Hasura Cloud, you will not need to restart your project and there will be no downtime.

Use cases

The following are a few configuration use cases: