Skip to main content
Version: v2.x

GraphQL Engine Server Configuration

Introduction​

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
Note

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'
services:
  postgres:
    image: postgres:12
    restart: always
    volumes:
      - db_data:/var/lib/postgresql/data
    environment:
      POSTGRES_PASSWORD: postgrespassword
  graphql-engine:
    image: hasura/graphql-engine:v2.15.0
    ports:
      - '8080:8080'
    depends_on:
      - 'postgres'
    restart: always
    environment:
      ## 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_DEV_MODE: 'true'
      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)
      # HASURA_GRAPHQL_CONSOLE_ASSETS_DIR: /srv/console-assets
      ## uncomment next line to set an admin secret
      # HASURA_GRAPHQL_ADMIN_SECRET: myadminsecretkey
volumes:
  db_data:

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:

Loading...
Loading...