Skip to main content
Version: v3.x (DDN)

Work with Multiple Repositories

Introduction​

Managing multiple repositories in Hasura DDN lets you streamline development across independent subgraphs while maintaining a unified supergraph. This approach provides flexibility for teams to work autonomously on their respective domains, all within a single coordinated API. By organizing your project into multiple repositories, you can iterate and deploy changes efficiently without impacting other subgraphs, ensuring a smooth and collaborative development experience.

You'll learn:

  • How to organize your project into subgraphs
  • How to provision a "parent" repo
  • How to set up your cloud project for multi-subgraph development
  • How to create independent subgraph repositories
  • How to create, test, and deploy your supergraph as subgraphs develop independently
  • How to create relationships across independent subgraphs

This tutorial takes about thirty minutes.

DDN Advanced Plan required

In order to utilize multi-repository collaboration, you must have an active DDN Advanced Plan.

Create the initial project​

Begin by creating a "parent project" that will serve as the coordinated supergraph for your independent subgraph repositories. The person creating this will assume the role of supergraph admin and have full control over provisioning subgraphs, inviting collaborators, and managing the API as a whole.

Step 1. Initialize a new local project​

Create a new local project and initialize a git repository:
ddn supergraph init parent-project && cd parent-project && git init

This will scaffold out the local configuration for a DDN project and initialize a git repository.

Step 2. Create a cloud project​

From the local project directory, create a new cloud project:
ddn project init

In .hasura/context.yaml, you'll see a new project key-value pair with the name of the project returned from the CLI.

Step 3. Create a commit​

Create an initial commit with your local project mapped to the cloud project via context:
git add . && git commit -m "Initial commit"

Step 4. Provision subgraphs​

We'll add two subgraphs to this supergraph: customers and billing.

Create the subgraphs on the cloud project:
ddn project subgraph create customers && ddn project subgraph create billing

Step 5. Create a supergraph build​

Create an initial supergraph build:
ddn supergraph build create

This will serve as the foundation for your first subgraph build to expand upon.

Step 6. Invite collaborators​

Head to the project's console at console.hasura.io and navigate to Setetings/Collaborators. Then, invite collaborators based on their role:

RoleDescription
Subgraph AdminUsers with permissions to create builds and deploy them to the parent project's endpoint.
Subgraph DeveloperDevelopers responsible for implementing features and making iterative changes to the subgraph's functionality.
Learn more about collaborators

Learn more about collaborators and roles here.

Each collaborator will receive an email inviting them to your project.

Add independent subgraphs to the project​

Each subgraph will live in its own repository. While this can be an existing repository, we're going to demonstrate initializing a new repository below.

Customers​

Step 1. Create a new repo for the customers subgraph​

Initialize a new local project and git repo:
ddn supergraph init customer-team --create-subgraph customers && cd customer-team && git init

This will scaffold out the necessary project structure along with initializing a git repository for version control.

Step 2. Map the local project to the existing cloud project​

Use the --with-project flag to map the local directory to the parent cloud project, replacing the name with your parent project's name:
ddn project init --with-project <project-name>

You'll see the project key-value pair updated in your .hasura/context.yaml file.

Step 3. Set the subgraph context​

Change the context to your subgraph's configuration file:
ddn context set subgraph ./customers/subgraph.yaml

This will set your unique subgraph in your .hasura/context.yaml file and make the CLI commands below more concise.

Step 4. Add prefixing​

Next, open the customers/subgraph.yaml file and add the following:
kind: Subgraph
version: v2
definition:
  name: customers
  generator:
    rootPath: .
    namingConvention: graphql
    graphqlRootFieldPrefix: customers_
    graphqlTypeNamePrefix: customers_
  includePaths:
    - metadata

These will prevent collisions of GraphQL root fields and GraphQL types when your supergraph is built.

Step 5. Add a data source and generate your first local build​

In this tutorial, we'll use the PostgreSQL connector and our sample PostgreSQL database:

postgresql://read_only_user:[email protected]:5432/v3-docs-sample-app
In your project directory, run the following, choose hasura/postrges, and pass the connection URI above when prompted:
ddn connector init customers_pg -i
Generate the Hasura metadata​
Next, use the CLI to introspect the PostgreSQL database:
ddn connector introspect customers_pg

After running this, you should see a representation of your database's schema in the customers/connector/customers_pg/configuration.json file; you can view this using cat or open the file in your editor.

Now, track the table from your PostgreSQL database as a model in your DDN metadata:
ddn models add customers_pg users

Open the customers/metadata directory and you'll find a newly-generated file: Users.hml. The DDN CLI will use this Hasura Metadata Language file to represent the users table from PostgreSQL in your API as a model.

Create a new local build and test the API​
To create a local build, run:
ddn supergraph build local

The build is stored as a set of JSON files in engine/build.

Start your local Hasura DDN Engine and PostgreSQL connector:
ddn run docker-start

Your terminal will be taken over by logs for the different services.

In a new terminal tab, open your local console:
ddn console --local
In the GraphiQL explorer of the console, write this query:
query GET_USERS {
  customers_users {
    id
    name
  }
}
You'll get the following response:
{
  "data": {
    "customers_users": [
      {
        "id": "7cf0a66c-65b7-11ed-b904-fb49f034fbbb",
        "name": "Sean"
      },
      {
        "id": "82001336-65b7-11ed-b905-7fa26a16d198",
        "name": "Rob"
      },
      {
        "id": "86d5fba0-65b7-11ed-b906-afb985970e2e",
        "name": "Marion"
      },
      {
        "id": "8dea1160-65b7-11ed-b907-e3c5123cb650",
        "name": "Sandeep"
      },
      {
        "id": "9bd9d300-65b7-11ed-b908-571fef22d2ba",
        "name": "Abby"
      }
    ]
  }
}

Step 6. Create a subgraph build​

Now that we've tested our local API and are happy with its state, we can create a build of our independent subgraph on our cloud project.

Create a subgraph build on your DDN project:
ddn subgraph build create

The CLI will return the subgraph's build version; you'll need this value in the next step.

Step 7. Create a supergraph build​

Begin by listing the available supergraph builds:
ddn supergraph build get

Grab the most recent build's version and use it — along with the subgraph build version — in the following command.

Finally, create a supergraph build incorporating your latest subgraph build:
ddn supergraph build create --subgraph-version customers:<build-version> --base-supergraph-version <supergraph-build-id>

The CLI will return a build URL for the console so you can explore your build and test your subgraph changes with others before applying the build to the supergraph. In order to apply the build, you must be a subgraph admin or higher:

ddn supergraph build apply <supergraph-build-version>
Make sure to stop all running services

As a multi-repository setup is intended to be utilized by multiple persons across teams, you're not likely to have multiple instances of your Hasura DDN Engine and other services running at the same time on your machine. Ensure you've killed all active services before proceeding to the next step for the billing subgraph.

Billing​

The steps below will allow you to incorporate your independent billing subgraph into your deployed supergraph API.

Step 1. Create a new repo for the billing subgraph​

Initialize a new local project and git repo:
ddn supergraph init billing-team --create-subgraph billing && cd billing-team && git init

This will scaffold out the necessary project structure along with initializing a git repository for version control.

Step 2. Map the local project to the existing cloud project​

Use the --with-project flag to map the local directory to the parent cloud project, replacing the name with your parent project's name:
ddn project init --with-project <project-name>

You'll see the project key-value pair updated in your .hasura/context.yaml file.

Step 3. Set the subgraph context​

Change the context to your subgraph's configuration file:
ddn context set subgraph ./billing/subgraph.yaml

This will set your unique subgraph in your .hasura/context.yaml file and make the CLI commands below more concise.

Step 4. Add prefixing​

Next, open the billing/subgraph.yaml file and add the following:
kind: Subgraph
version: v2
definition:
  name: billing
  generator:
    rootPath: .
    namingConvention: graphql
    graphqlRootFieldPrefix: billing_
    graphqlTypeNamePrefix: billing_
  includePaths:
    - metadata

Like before, this will ensure the types an fields are namespaced to your subgraph.

Step 5. Add a data source and generate your first local build​

As before, we'll use the PostgreSQL connector with our sample database:

postgresql://read_only_user:[email protected]:5432/v3-docs-sample-app
In your project directory, run:
ddn connector init billing_pg -i
Generate the Hasura metadata​
Next, use the CLI to introspect the PostgreSQL database:
ddn connector introspect billing_pg

After running this, you should see a representation of your database's schema in the billing/connector/billing_pg/configuration.json file; you can view this using cat or open the file in your editor.

Now, track the table from the PostgreSQL database as a model in your DDN metadata:
ddn models add billing_pg orders

Open the billing/metadata directory and you'll find a newly-generated file: Orders.hml. The DDN CLI will use this Hasura Metadata Language file to represent the orders table from PostgreSQL in your API as a model.

Create a new local build and test the API​
To create a local build, run:
ddn supergraph build local

The build is stored as a set of JSON files in engine/build.

Start your local Hasura DDN Engine and PostgreSQL connector:
ddn run docker-start

Your terminal will be taken over by logs for the different services.

In a new terminal tab, open your local console:
ddn console --local
In the GraphiQL explorer of the console, write this query:
query GET_ORDERS {
  billing_orders {
    id
    createdAt
    status
  }
}
You'll get the following response:
{
  "data": {
    "billing_orders": [
      {
        "id": "c7406b75-6b24-41e4-9c5b-ff3feada9447",
        "createdAt": "2023-10-29T17:02:50.889261+00:00",
        "status": "processing"
      },
      {
        "id": "7ff13435-b590-4d6b-957f-f7fd39d4528a",
        "createdAt": "2023-10-29T17:02:50.958076+00:00",
        "status": "complete"
      },
      {
        "id": "98612470-1feb-4b91-88f7-9289d652ee87",
        "createdAt": "2023-10-29T17:02:51.021317+00:00",
        "status": "complete"
      },
      {
        "id": "85581445-752a-4aef-9684-b648eb5d5f42",
        "createdAt": "2023-10-29T17:02:51.085229+00:00",
        "status": "complete"
      },
      {
        "id": "9891596a-a732-4c1c-902c-1a112da48fec",
        "createdAt": "2023-10-29T17:02:51.150084+00:00",
        "status": "complete"
      }
    ]
  }
}

Step 6. Create a subgraph build​

Once your local metadata is in its desired state, create a subgraph build on your DDN project:
ddn subgraph build create

The CLI will return the subgraph's build version; you'll need this value in the next step.

Step 7. Create a supergraph build​

Begin by listing the available supergraph builds:
ddn supergraph build get

Grab the most-recent build's version and use it — along with the subgraph build version — in the following command.

Finally, create a supergraph build incorporating your latest subgraph build:
ddn supergraph build create --subgraph-version billing:<build-version> --base-supergraph-version <supergraph-build-id>

The CLI will return a build URL for the console so you can explore your build and test your subgraph changes with others before applying the build to the supergraph. In order to apply the build, you must be a subgraph admin or higher:

ddn supergraph build apply <supergraph-build-version>
Make sure to stop all running services

As a multi-repository setup is intended to be utilized by multiple persons across teams, you're not likely to have multiple instances of your Hasura DDN Engine and other services running at the same time on your machine. Ensure you've killed all active services before proceeding to the next step.

Add a cross-subgraph relationship​

We can create relationships across subgraphs that are testable on a Hasura Cloud project. As your locally-running engine will only have access to your local subgraphs and their accompanying metadata, you'll need to define relationships using your knowledge of other subgraphs and then test them using a supergraph build in your hosted environment.

Add the following relationship object to your Users.hml file in your customer-team repo:
---
kind: Relationship
version: v1
definition:
  name: orders
  sourceType: Users
  target:
    model:
      subgraph: billing
      name: Orders
      relationshipType: Array
  mapping:
    - source:
        fieldPath:
          - fieldName: id
      target:
        modelField:
          - fieldName: userId
Create a new subgraph build:
ddn subgraph build create
Get the list of supergraph builds:
ddn supergraph build get
Then, create a supergraph build incorporating your latest subgraph build:
ddn supergraph build create --subgraph-version customers:<build-version> --base-supergraph-version <supergraph-build-id>
Now, you can test your nested query across subgraphs:
query GET_USERS_AND_ORDERS {
  customers_users {
    id
    name
    orders {
      id
      createdAt
      status
    }
  }
}
With a repsonse like this:
{
  "data": {
    "customers_users": [
      {
        "id": "7cf0a66c-65b7-11ed-b904-fb49f034fbbb",
        "name": "Sean",
        "orders": [
          {
            "id": "7ff13435-b590-4d6b-957f-f7fd39d4528a",
            "createdAt": "2023-10-29T17:02:50.958076+00:00",
            "status": "complete"
          }
        ]
      },
      {
        "id": "82001336-65b7-11ed-b905-7fa26a16d198",
        "name": "Rob",
        "orders": [
          {
            "id": "9891596a-a732-4c1c-902c-1a112da48fec",
            "createdAt": "2023-10-29T17:02:51.150084+00:00",
            "status": "complete"
          }
        ]
      },
      {
        "id": "86d5fba0-65b7-11ed-b906-afb985970e2e",
        "name": "Marion",
        "orders": [
          {
            "id": "85581445-752a-4aef-9684-b648eb5d5f42",
            "createdAt": "2023-10-29T17:02:51.085229+00:00",
            "status": "complete"
          }
        ]
      },
      {
        "id": "8dea1160-65b7-11ed-b907-e3c5123cb650",
        "name": "Sandeep",
        "orders": [
          {
            "id": "c7406b75-6b24-41e4-9c5b-ff3feada9447",
            "createdAt": "2023-10-29T17:02:50.889261+00:00",
            "status": "processing"
          }
        ]
      },
      {
        "id": "9bd9d300-65b7-11ed-b908-571fef22d2ba",
        "name": "Abby",
        "orders": [
          {
            "id": "98612470-1feb-4b91-88f7-9289d652ee87",
            "createdAt": "2023-10-29T17:02:51.021317+00:00",
            "status": "complete"
          }
        ]
      }
    ]
  }
}

Recap​

By organizing your project into multiple repositories, you can create a flexible and collaborative workflow for subgraph development in Hasura DDN. Starting with a parent project, you learned how to provision subgraphs, invite collaborators, and manage builds to integrate subgraph changes into a unified supergraph. This structure ensures teams can work independently while maintaining seamless integration and coordination across the entire API.

© 2025 Hasura Inc. All rights reserved