Skip to content

Develop and release a Subgraph

Test each version of your Subgraph while production keeps serving, then release it without changing your application URL.

Build your Subgraph through as many versions as you need while your production application keeps serving the version you released. You test each candidate through its own Deployment CID, and your application moves only when you promote a candidate that is indexed and ready.

This guide uses one Managed Subgraph as your release pipeline: its Current version serves production, and its Next version is the candidate you are testing.

Prerequisites

  • An Owner or Developer role in a GraphOps organization with Subgraphs access.
  • The requirements to start indexing: available credits, room in your plan and a supported network.
  • A Subgraph project you can build and deploy with Graph CLI, as in Deploy your own Subgraph.
  • A Subgraphs API key.

Set up once

Create the Managed Subgraph

Deploy your first version with Graph CLI and record its Deployment CID. Create a Managed Subgraph with a Deployment CID target from that CID, so each release waits for your approval.

Create the production Endpoint Alias

Create an Endpoint Alias named for your application, such as orders, with a Managed Subgraph target. You can add it in the last step of creating the Managed Subgraph. Configure your production application with its URL:

Reference

https://subgraphs.graphops.xyz/v1/alias/<ALIAS>

Optionally, create a development Endpoint Alias

If your development or staging environment should keep one URL across candidates, create a second Endpoint Alias, such as orders-dev, with a Deployment CID target. You point it at each candidate as you stage it.

Test a new version

  1. Deploy the change with Graph CLI and record the new Deployment CID.
  2. On the Managed Subgraph, choose Start upgrade and enter the CID. GraphOps checks it as you enter it; continue once it passes, then review the schema comparison, which lists changes that can break your existing queries.
  3. Query the candidate while it indexes through its Deployment CID endpoint, or through your development Endpoint Alias after you point it at the CID with Change target. Check _meta.block.number to see how far it has indexed; results are incomplete until it catches up.
  4. If you find a problem, choose Cancel upgrade, deploy a fix and stage the new CID. A Managed Subgraph has one Next version at a time, so point your development Endpoint Alias at the new candidate too.

Your production Endpoint Alias keeps serving Current throughout. Each staged version indexes from its start block and accrues indexing charges while it is staged, alongside Current.

Release the version

  1. Update and deploy any clients affected by schema changes before you release.
  2. Wait until Next shows Ready to promote. It must be healthy and close to the network head.
  3. Choose Promote version. Your production Endpoint Alias moves to the new version, and your application keeps the same URL.
  4. Query _meta.deployment through the production Endpoint Alias to confirm the CID it serves.

Record each released Deployment CID. The previous version is removed after promotion.

Roll back

Returning to a previous version is another upgrade, not an instant switch. Stage the previous Deployment CID as Next, let it index, and promote it when it is ready. Plan for that indexing time in your release process, and fix forward when a corrected version would be ready sooner.

Keep a separate development environment

One Managed Subgraph is enough when you test one candidate at a time. Create a second Managed Subgraph for development when you need a development version that keeps running, such as for a long-lived staging environment, while production upgrades separately:

  • Point your development Endpoint Alias at the development Managed Subgraph with a Managed Subgraph target, and promote there as often as you like.
  • To release, stage the tested Deployment CID on the production Managed Subgraph and promote it when it is ready.

Each Managed Subgraph uses its own plan slot and accrues its own indexing charges, even when both index the same Deployment CID.

Release by publishing on The Graph Network

If your team publishes the Subgraph on The Graph Network, you can make that publication the release. Create the production Managed Subgraph with a Graph Network Subgraph ID target for your Subgraph's ID. Each version you publish becomes Next and is promoted automatically when it is ready, including breaking schema changes.

Because publishing releases the version, test each candidate before you publish it, for example in a development Managed Subgraph with a Deployment CID target. Point your production application at an Endpoint Alias that targets the production Managed Subgraph, not at the subgraphId endpoint, which moves to each publication before it is indexed.

Before production

  • Point production clients at an Endpoint Alias, never at a candidate's Deployment CID.
  • Keep a record of each released Deployment CID and the schema your clients expect.
  • Log _meta.deployment with production queries so you can tell which version served a request.
  • Check that your credit balance covers both versions during an upgrade; see Plan indexing costs.

Next steps

Deploy your own Subgraph

Build your Subgraph with Graph CLI, deploy or publish it, and use its identifier in GraphOps.

Manage Endpoint Aliases

Keep a stable query URL by targeting a Deployment CID, a Managed Subgraph, or a Graph Network Subgraph ID, and choose which version it serves.