Independent Subgraph Development
Teams working on larger projects may want a software development lifecycle (SDLC) and CI/CD which is independent of other teams. This is where independent subgraph, multi-repo federation shines on the DDN Advanced plan
Subgraphs in this multi-repo federation are managed in their own repository for added governance, control and clean
separation from other teams work. Users and teams can be added to individual subgraphs on Hasura DDN as
admins or developers, allowing them to work independently on their subgraph
and data connectors without affecting other subgraphs. Subgraphs would also typically be named for and given
responsibility over the data domain they encapsulate, such as users, orders, products, etc.
You will need a project on the DDN Advanced plan to use independent subgraph development with a multi-repo setup.
- Supergraph and subgraph builds are immutable and have a unique id.
- Subgraph builds are added to the DDN project with the same name as defined in the subgraph's
subgraph.yamlfile. - A subgraph must already exist in the DDN project in order to invite a collaborator to it.
- A supergraph build can be made by composing subgraphs and a base supergraph version. If no base supergraph version is provided, the applied supergraph version will be used.
- A local independent subgraph development project must still have a supergraph with global objects defined (as in the
default
globalssubgraph). Only supergraphs have APIs. - A local independent subgraph development project context will reference the DDN project used for collaboration.
- Each subgraph is namespaced and internal metadata objects cannot conflict with other subgraphs. However, the GraphQL API is where the subgraphs meet and conflicts can occur with root field and type names. Prefixing subgraphs will remedy this automatically or it can be managed manually.
Creating a new project with independent subgraph development
Creating the initial project
The setup here is for a main supergraph repository to be created with the globals subgraph and placeholders for any
other subgraph which other teams will work on. Once on DDN, collaborators are added on the subgraph level giving them
permissions to only work on their subgraph.
By convention, the globals subgraph contains supergraph-level metadata objects that apply to the entire supergraph.
These are AuthConfig, CompatibilityConfig and GraphqlConfig as well as the Subgraph object which defines the
globals subgraph itself.
- As a supergraph admin, create a supergraph normally, deploy and apply on Hasura DDN, as per the getting started guide.
- Create any other subgraphs which other teams will work on as placeholders so that they can be invited to them. You
can do this with
ddn project subgraph create <subgraph-name> [flags] - Push the supergraph to a new Git repository. Do not add collaborators to this repo, they will be added to / create their own subgraph repositories.
- Invite subgraph collaborators to the Hasura DDN project with Subgraph Admin or Subgraph Developer permissions.
Joining the project
Now, collaborators manage a separate local supergraph repo for development containing just their subgraph and changes the supergraph context to reference the collaborative project on DDN.
The supergraph enables local development but only contains their subgraph. They can then create subgraph builds on the collaborative DDN project and, if permissions allow, apply the subgraph to the collaborative supergraph.
- Accept the invitation to the Hasura DDN supergraph project.
- Create a new Git repository for a new supergraph.
- Initialize a new supergraph with a subgraph locally. Make sure the subgraph is named the same as the subgraph you
were invited to work on. You can do this with:
ddn supergraph init . --create-subgraph <subgraph-name> - It's recommended to setup subgraph prefixes at this stage.
- Run your supergraph locally and develop and test.
- Map your local project to the existing project on DDN. You can do this with:
ddn project init --with-project <project-name> - Create a subgraph build on the existing Hasura DDN supergraph project.
You can do this with:
ddn subgraph build create - Create a supergraph build on Hasura DDN. You can do this with:
ddn supergraph build create --subgraph-version <subgraph-name:build-version> --base-supergraph-version <supergraph-build-id> - Deploy your subgraph changes if permissions allow. Otherwise, request the owner or admin to apply the subgraph. You
would do this with either
ddn subgraph build apply <subgraph-build-version>orddn supergraph build apply <supergraph-build-version>
If you already have an existing app or other repository to which you feel it appropriate to add your DDN project configuration in a new directory, that's fine too!
Merging two existing projects
If you have two existing projects on Hasura DDN which were developed independently that you would like to merge into a single DDN project with independent subgraph development, you can do so by following these steps:
- Choose which project will be the main project and which will be the subgraph project.
- In the main project, create a new subgraph placeholder for the subgraph project with
ddn project subgraph create <subgraph-name> [flags] - On DDN, invite the subgraph project collaborators with subgraph permissions.
- Once the subgraph collaborators have accepted the invitation, they can
set the project context to the main project with
ddn context set project <main-project-name>. - Subgraph collaborators may also at this stage set subgraph prefixes to prevent conflicts with the main project if needed.
- The subgraph collaborators can then create a subgraph build on the main project with
ddn subgraph build create. - The main project owner or admin can then apply the subgraph build to the main project with
ddn subgraph build apply <subgraph-build-version>.
