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
├── .env
├── .gitattributes
├── .gitignore
├── .hasura
│   └── context.yaml
├── .vscode
│   ├── extensions.json
│   ├── launch.json
│   └── tasks.json
├── app
│   ├── metadata
│   └── subgraph.yaml
├── compose.yaml
├── engine
│   ├── .env.engine
│   └── build
│       ├── auth_config.json
│       ├── metadata.json
│       └── open_dd.json
├── globals
│   ├── auth-config.hml
│   ├── compatibility-config.hml
│   ├── graphql-config.hml
│   └── subgraph.yaml
├── hasura.yaml
├── otel-collector-config.yaml
└── supergraph.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: v3

• 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

When a new project directory is initialized with the DDN CLI, it creates a single .env file by default. This .env file will store all the environment variables required for local development.

ddn project init command will initialize a single .env.cloud file which will be used to store all environment variables required by the DDN project.

It is also possible to split the .env file into different .env files required for:

• Docker Compose: Docker Compose files can use .env files to specify environment variables needed for containers.
• Subgraph files (such as subgraph.yaml): Each subgraph can have its own .env file which will be used to specify environment variables required for building the subgraph.
• Connector files (such as connector.yaml): Each connector file can have its own .env file which will be used to specify environment variables needed for building the connector.

Other than this, .env files can also be passed into various DDN commands using --env-file flag.

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 a single supergraph file - supergraph.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: v2
definition:
  name: app
  generator:
    rootPath: .
  includePaths:
    - metadata
  envMapping:
    POSTGRES_READ_URL:
      fromEnv: APP_POSTGRES_READ_URL
    POSTGRES_WRITE_URL:
      fromEnv: APP_POSTGRES_READ_URL
  connectors:
    - path: connector/mypg/connector.yaml
      connectorLinkName: mypg

• 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.
• envMapping declares the environment variables needed by the subgraph and where to read it from. For example,

  POSTGRES_WRITE_URL:
     fromEnv: APP_POSTGRES_WRITE_URL
  This means that some metadata in the subgraph requires an env var called POSTGRES_WRITE_URL. The value of this has to be read from an env var called APP_POSTGRES_WRITE_URL from any of the .env.* files passed as input. Only env vars declared in the envMapping are passed into the subgraph.
• connectors lists all the connectors that are to be built when this subgraph is built. It contains path to the connector configuration and the name of the corresponding connector link.

By default, the CLI generates a single 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: v2
definition:
  name: mypg
  source: hasura/postgres:v1.0.1
  context: .
  envMapping:
    CONNECTION_URI:
      fromEnv: APP_MYPG_CONNECTION_URI

• 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
• envMapping declares the environment variables needed by the connector and where to read it from. It works the same way as it does for subgraphs. Only env vars declared in the envMapping are passed into the connector.

By default, the CLI generates a single connector.yaml file for every new connector that is added but any number of connector config files can be created and referenced in CLI commands.

.hasura/context.yaml

This specifies the different contexts set up for the project. Contexts allow setting default values for certain flags that are often needed in CLI commands. By default, a context called default is created and set as the current context.

• project is used for all commands that need a DDN project. Used when the --project flag is not provided.
• supergraph is used for all commands that need a supergraph config file. Used when the --supergraph flag is not provided.
• subgraph is used for all commands that need a subgraph config file. Used when the --subgraph flag is not provided.
• localEnvFile is used by default by all local development commands (like ddn supergraph build local). Used when the --env-file flag is not provided.
• cloudEnvFile is used by default by all cloud commands (like ddn supergraph build create). Used when the --env-file flag is not provided.

The scripts section defines all the scripts which can be run using ddn run command.

kind: Context
version: v3
definition:
  current: default
  contexts:
    default:
      project: emerging-stag-9129
      supergraph: ../supergraph.yaml
      subgraph: ../app/subgraph.yaml
      localEnvFile: ../.env
      cloudEnvFile: ../.env.cloud
  scripts:
    docker-start:
      bash: HASURA_DDN_PAT=$(ddn auth print-pat) docker compose --env-file .env up --build --pull always -d
      powershell: $Env:HASURA_DDN_PAT = ddn auth print-pat; docker compose --env-file .env up --build --pull always -d

This file can be configured using the ddn context set of commands.

Engine

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

.
├── .env.engine
└── build
    ├── 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.

All files inside build directory are ignored by default by the .gitignore file generated by the CLI.

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:

.
├── auth-config.hml
├── compatibility-config.hml
├── graphql-config.hml

• auth-config.hml contain the AuthConfig object which define the authentication configuration for the supergraph.
• 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.