Configuration

Introduction

Hasura v3 introduces a new configuration for local projects.

Sample project directory structure

The following is a sample directory structure of a local project:

.
├── .devcontainer
│  └── devcontainer.json
├── .hasura
│  └── context.yaml
├── .vscode
│  ├── extensions.json
│  ├── launch.json
│  └── tasks.json
├── engine
│  ├── .env.engine
│  ├── auth_config.json
│  ├── metadata.json
│  └── open_dd.json
├── globals
│  ├── .env.globals.cloud
│  ├── .env.globals.local
│  ├── subgraph.cloud.yaml
│  ├── subgraph.local.yaml
│  ├── auth-config.cloud.hml
│  ├── auth-config.local.hml
│  ├── compatibility-config.hml
│  └── graphql-config.hml
├── app
│  ├── .env.app.cloud
│  ├── .env.app.local
│  └── subgraph.yaml
├── .gitattributes
├── compose.yaml
├── hasura.yaml
├── otel-collector-config.yaml
├── supergraph.cloud.yaml
└── supergraph.local.yaml

Types of files

The new configuration relies on the following types of files:

File type	Description
hasura.yaml	The file that denotes the root of a Hasura project.
.env.*	Files that store environment variables.
supergraph.*.yaml	Files that describe how to build the supergraph.
subgraph.*.yaml	Files that describe how to build a subgraph.
connector.*.yaml	Files that describe how to build a data connector.
*.hml	Hasura metadata files for a project.
.hasura/context.yaml	File that stores certain default values of a project.
compose.yaml	Docker Compose files for local development.
engine	Files mounted to the engine container for local development.
globals	Directory containing files for the globals subgraph.
otel-collector-config.yaml	Configuration for OpenTelemetry Collector used for seeing traces during local development.

hasura.yaml

hasura.yaml appears at the root of a Hasura project.

For example:

version: v2

• version specifies the version of the project directory structure.

.env.*

This file is used to store environment variables. The file should be in the format:

ENV1=val1
ENV2=val2

These files are referenced inside:

• Docker Compose files: Docker Compose files use *.env files to specify environment variables needed for containers.
• Subgraph files: Subgraph files use *.env files to specify environment variables. This is needed by globals and other subgraphs. Each subgraph can have its own .env file.
• Connector files (such as connector.yaml): Connector files use *.env files to specify environment variables needed for building the connector.

supergraph.*.yaml

These config files tell Hasura DDN how to construct your supergraph. It will contain information such as which subgraph config files to use for building the supergraph

For example:

kind: Supergraph
version: v2
definition:
  subgraphs:
    - globals/subgraph.cloud.yaml
    - app/subgraph.yaml

• version is the version of the supergraph object
• subgraphs specifies paths to all the subgraph config files. These are then read recursively to construct the metadata for the supergraph.

By default, the CLI generates two files - supergraph.cloud.yaml and supergraph.local.yaml but any number of supergraph config files can be created and referenced in CLI commands.

subgraph.*.yaml

These config files tell Hasura DDN how to construct your subgraph. It will contain information such as which metadata resources to use for the build.

For example:

kind: Subgraph
version: v1
definition:
  name: app
  generator:
    rootPath: .
  includePaths:
    - metadata

• version is the version of the subgraph object
• includePaths specifies the directories and files where metadata for the subgraph can be found. If a directory is specified, all the *.hml files inside the directory and its subdirectories will be used to construct the metadata.
• generator.rootPath specifies the directory into which any new files will be generated.

By default, the CLI generates a file called subgraph.yaml for a new subgraph but any number of subgraph config files can be created and referenced in CLI commands.

connector.*.yaml

These config files tell Hasura DDN how to build your connector. It will contain information such as the type of connector and the location to the context files needed to build the connector.

For example:

kind: Connector
version: v1
definition:
  name: mypg
  source: hasura/postgres:v0.7.0
  context: .
  envFile: .env.local

• version is the version of the connector object
• name is a name given to the connector
• source is the connector to use specific to the data source
• context specifies the connector directory
• envFile specifies the connector specific environment variables to use for introspecting and building the connector. If you are deploying your connector on DDN cloud, you also need to specify subgraph. Value of this field is name of the subgraph you want to deploy your connector to.

By default, the CLI generates two files - connector.cloud.yaml and connector.local.yaml but any number of connector config files can be created and referenced in CLI commands.

.hasura/context.yaml

This specifies the default DDN project and supergraph file path. The default values are used by all commands that accept --supergraph flag, --subgraph flag and --project flag. The flags can be used to override the default values.

context:
  project: emerging-stag-9129
  supergraph: ../supergraph.cloud.yaml
  subgraph: ../app/subgraph.yaml

This file is configured by the ddn context set command.

Engine

The engine directory contains the files required for Hasura v3 engine container. This directory has the following structure:

├── .env.engine
├── auth_config.json
├── metadata.json
└── open_dd.json

The .env.engine file specifies environment variables required by the Hasura v3 engine container.

The auth_config.json, metadata.json and open_dd.json are generated as a result of ddn supergraph build local command and do not need to be edited by the user.

Globals

The globals directory contains the files for the globals subgraph which is generated by default to hold the supergraph-level metadata objects, i.e. AuthConfig, GraphqlConfig and CompatibilityConfig.

For example:

├── .env.globals.cloud
├── .env.globals.local
├── auth-config.cloud.hml
├── auth-config.local.hml
├── compatibility-config.hml
├── graphql-config.hml
├── subgraph.cloud.yaml
└── subgraph.local.yaml

• auth-config.cloud.hml and auth-config.local.hml files contain the AuthConfig object which define the authentication configuration for the supergraph for cloud and local deployments respectively.
• compatibility-config.hml file contains the compatibility date configuration for the supergraph.
• graphql-config.hml file contains the GraphQL configuration for the supergraph, which allows you to customize the available query and mutation capabilities along with the schema.
• .env.globals.cloud and .env.globals.local files contain all the environment variables, if any, which are required by the globals subgraph's metadata objects for cloud and local deployments respectively.