Rename a subgraph

Introduction

In this recipe, you'll learn how to rename a subgraph in your local project directory.

Prerequisites

Before continuing, ensure you have:

• A local Hasura DDN project.
• Stopped any running docker services related to the project.

Recipe

Step 1. Update subgraph config files

Update the name of the subgraph in all the subgraph config files of the subgraph. The subgraph config is typically located at <subgraph-name>/subgraph.yaml.

<subgraph-name>/subgraph.yaml

kind: Subgraph
version: v2
definition:
  name: <new-subgraph-name>
  generator:
    rootPath: .
  includePaths:
    - metadata
  envMapping: ...

Step 2. Update connector config files of the subgraph

Update the reference of the subgraph in all the connector config files of all the connectors belonging to the subgraph. The connector config is typically located at <subgraph-name>/connector/<connector-name>/connector.yaml.

<subgraph-name>/connector/<connector-name>/connector.yaml

kind: Connector
version: v2
definition:
  name: <connector-name>
  subgraph: <new-subgraph-name>
  source: hasura/<connector-type>
  context: .
  envMapping: ...

Step 3. Update compose files of connectors of the subgraph

Update the name of the connector service in the compose file of all the connectors belonging to the subgraph. The connector compose file is typically located at <project-root>/<subgraph-name>/connector/<connector-name>/compose.yaml.

<subgraph-name>/connector/<connector-name>/compose.yaml

services:
  <new-subgraph-name>_<connector-name>:
    build:
      context: .
      dockerfile_inline: ...

Step 4. (Optional) Update subgraph directory name

The subgraph directory is typically named as the subgraph name itself. The directory name does not impact any functionality, but you might want to rename it to maintain consistency. The subgraph directory is typically located at the project root, i.e., <project-root>/<subgraph-name>/.

Rename the directory to <project-root>/<new-subgraph-name>/.

Renaming the subgraph directory name will require updates to any references to files within the directory. These should typically be in:

Step 4.1. Supergraph config files

Update the path to the subgraph config files in all supergraph config files. The supergraph config file is typically located at the project root, i.e., <project-root>/supergraph.yaml.

supergraph.yaml

kind: Supergraph
version: v2
definition:
  subgraphs:
    - globals/subgraph.yaml
    - <new-subgraph-name>/subgraph.yaml
    ...

Step 4.2. Engine compose file

Update the path to the connector compose files included in the engine compose file. The engine config file is typically located at the project root, i.e., <project-root>/compose.yaml.

compose.yaml

include:
  - path: <new-subgraph-name>/connector/<connector-1>/compose.yaml
  - path: <new-subgraph-name>/connector/<connector-2>/compose.yaml
  ...
services:
  engine:
    build:
    ...

Step 4.3. Context config

The context config file located at .hasura/context.yaml may have the subgraph config file path saved in the context. Update the subgraph config path if set.

.hasura/context.yaml

kind: Context
version: v3
definition:
  current: default
  contexts:
    default:
      supergraph: ../supergraph.yaml
      subgraph: ../<new-subgraph-name>/subgraph.yaml
      ...

Learn more

• Project configuration