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, from the GraphOps CLI, GraphOps Platform or CI.

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. Each step shows the GraphOps CLI command and the GraphOps Platform action that do the same thing; use whichever fits your workflow.

Prerequisites

  • A Managed Subgraph with a Deployment CID target, so each release waits for your approval. Deploy your own Subgraph creates one.
  • The owner or developer role, and the requirements to start indexing: available credits, room in your plan, and a supported network.
  • A query key that includes Subgraphs.

Managed indexing accrues charges while a version is indexed, whether or not it receives queries. Each version you stage indexes from its start block and accrues charges alongside Current, so check that your credit balance covers both during an upgrade.

Set up your Endpoint Aliases once

Create the production Endpoint Alias

Create an Endpoint Alias named for your application, such as orders, with a Managed Subgraph target and the Current version behavior. It moves to each version you promote. With the GraphOps CLI, run graphops subgraphs endpoint-aliases create orders --managed-subgraph my-subgraph; in GraphOps Platform, 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 staging Endpoint Alias

If your development or staging environment should keep one URL across candidates, create a second Endpoint Alias, such as orders-staging, with the same Managed Subgraph target and the Next version behavior (--behavior next). It serves each candidate as soon as it can answer queries, and falls back to Current between releases. Endpoint Aliases explains each behavior.

Test a new version

Stage the change as the Next version, then query it while it indexes. Your production Endpoint Alias keeps serving Current throughout.

With the GraphOps CLI, deploy again from the same project. The CLI builds, uploads and stages the build as Next. Deploying a build that is already Current or Next changes nothing.

CLI · GraphOps CLI

# Stages the new build as the Next version. The Current version keeps serving.
graphops subgraphs deploy my-subgraph

The deploy prints the Next version's query URL for testing. It stops instead of staging in these cases:

  • A Next version is already staged. The CLI stops before building, because it can't know the new build's Deployment CID until Graph CLI uploads it. If the staged version is the one you want, wait for it and promote it. Otherwise deploy with --replace-next to cancel it and stage the new build, or remove it with graphops subgraphs unstage my-subgraph. With --replace-next, a build of the staged Deployment CID itself changes nothing.
  • Graph CLI's --network names another network than the Managed Subgraph's. The CLI stops before building. Without --network, GraphOps refuses the uploaded build instead.
  • The new schema is not compatible with Current. The CLI lists the issues. Check the queries your application sends, then deploy again with --accept-schema-changes.

From GraphOps Platform, build and upload with Graph CLI as in Deploy from GraphOps Platform, then:

  1. On the Managed Subgraph, choose Start upgrade and enter the new 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.
  2. 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.

Query the candidate through its Deployment CID endpoint or your staging Endpoint Alias. Check _meta.block.number to see how far it has indexed. Results are incomplete until it catches up.

Release the version

  1. Update and deploy any clients affected by schema changes before you release.
  2. Wait until Next can be promoted: healthy and close to the network head. GraphOps Platform shows Ready to promote, and graphops subgraphs wait --for promotable returns.
  3. Promote it with graphops subgraphs promote, or choose Promote version. Next becomes Current, and your production Endpoint Alias moves to it while your application keeps the same URL. The CLI names the Endpoint Aliases that now serve it.
  4. Query _meta.deployment through the production Endpoint Alias to confirm the CID it serves.

CLI · GraphOps CLI

graphops subgraphs wait my-subgraph --for promotable --timeout 2h
graphops subgraphs promote my-subgraph

If GraphOps refuses the promotion, for example because the Next version has not caught up or you lack the permission, the CLI prints the reason and exits with code 5. The previous version is removed after promotion, so its Deployment CID query URL stops working. Record each released Deployment CID.

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.

With the GraphOps CLI, graphops subgraphs history my-subgraph lists the Next, Current and previous versions, newest first. Deploy the CID you want with --cid, which stages it as Next without building, then promote it:

CLI · GraphOps CLI

# Find the Deployment CID of the earlier release: Next, Current and previous versions, newest first.
graphops subgraphs history my-subgraph
# Stage it in place of any Next version. It indexes again from its start block.
graphops subgraphs deploy my-subgraph --cid <PREVIOUS_DEPLOYMENT_CID> --replace-next
graphops subgraphs wait my-subgraph --for promotable
graphops subgraphs promote my-subgraph --expect-next <PREVIOUS_DEPLOYMENT_CID>

In GraphOps Platform, choose Start upgrade and enter the previous CID.

Release from CI

Run the same commands in CI as a service account. Set GRAPHOPS_TOKEN to one of its service account API keys, stored as a secret of your CI system. Install an exact CLI version in CI, as Run the CLI in CI shows, so a new release can't change the JSON your job reads.

CLI · GraphOps CLI

# GRAPHOPS_TOKEN holds a service account API key from your CI system's secrets.
# --replace-next replaces any staged Next version, even one someone else staged: drop it when
# several pipelines release the same Managed Subgraph.
result=$(graphops -o json subgraphs deploy my-subgraph --replace-next)
CID=$(printf '%s' "$result" | jq -r .deploymentCid)
case $(printf '%s' "$result" | jq -r .outcome) in
  staged | replaced | already_staged)
    graphops subgraphs wait my-subgraph --for promotable --timeout 2h
    graphops subgraphs promote my-subgraph --expect-next "$CID"
    ;;
  # already_current (and created, with --create): the build already serves; nothing to promote.
esac

The job reads the outcome of graphops -o json subgraphs deploy to decide what comes next, so running it again for the same build succeeds:

outcomeMeaningNext step
created--create created the Managed Subgraph from the buildNone: it is Current. Wait with --for synced if the job needs it ready.
stagedThe build is the Next versionWait with --for promotable, then promote
replaced--replace-next cancelled the previous Next version and staged the buildWait with --for promotable, then promote
already_currentThe build is already CurrentNone
already_stagedThe build is already the Next versionWait with --for promotable, then promote

To promote exactly the build the job staged, pass the deploy's deploymentCid to graphops subgraphs promote --expect-next. The promotion then stops with code 5 and next_changed if another version was staged meanwhile.

The service account needs these permissions. CLI messages name them by ID.

CommandPermissions
list, status, history, waitRead Managed Subgraphs (managedSubgraphs.read)
deploy a new versionRead Managed Subgraphs and Stage deployments (managedSubgraphs.stage)
deploy --replace-nextRead Managed Subgraphs, Stage deployments and Cancel Next (managedSubgraphs.unstage)
unstageRead Managed Subgraphs and Cancel Next
promoteRead Managed Subgraphs and Promote Next (managedSubgraphs.promote). With Read Endpoint Aliases (endpointAliases.read) it also names the Endpoint Aliases now serving the new version; without it, it warns and still succeeds.
deploy --create, createRead Managed Subgraphs and Create Managed Subgraphs (managedSubgraphs.create), plus Reconfigure Managed Subgraphs (managedSubgraphs.reconfigure) to follow a Graph Network Subgraph ID

A permission limited to named Managed Subgraphs works only on those. Creating a Managed Subgraph acts on the whole organization, so a service account that creates one needs these permissions without a limit.

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

Last updated