Go from your Subgraph project to an indexing Managed Subgraph with one command.
graphops subgraphs deploy runs your project's Graph CLI to build and upload the Subgraph, then
creates the Managed Subgraph or stages the build as its Next version. A new version serves queries
only when you promote it.
Prerequisites
- A Subgraph project with
subgraph.yamland Graph CLI in its dependencies. - The GraphOps CLI, signed in to your organization.
- A monthly plan with room for another Managed Subgraph. Managed indexing accrues charges while a version is indexed, whether or not it receives queries.
Create the Managed Subgraph
Deploy with --create
Run the deploy from your project. The name you pass names the Managed Subgraph, and Graph CLI uses
it as the Subgraph name. --create is required the first time, because indexing and its charges
start when the Managed Subgraph is created. Without it, the CLI stops before building when no
Managed Subgraph has that name.
CLI · GraphOps CLI
# Run from your Subgraph project. Builds with your graph-cli and creates the Managed Subgraph.
graphops subgraphs deploy my-subgraph --create
Graph CLI's build output appears as usual. Graph CLI deploys through a local GraphOps bridge, so
the Graph node address it prints is on 127.0.0.1. The CLI then prints the
Deployment CID, the network, the query URL and a link to the Managed Subgraph
in GraphOps Platform. A Managed Subgraph indexes one network: to index the same Subgraph on another network,
deploy it under another name, for example with the network in the name.
Wait for it to sync
CLI · GraphOps CLI
# Wait until the current version has caught up with the network (default timeout 30m).
graphops subgraphs wait my-subgraph --for synced
graphops subgraphs status my-subgraph
--for synced waits until the Current version has caught up with the network. The wait gives up
after 30 minutes by default, exiting with code 6; indexing continues, so wait again or check
graphops subgraphs status. The wait stops at once with code 5 if the deployment reports a
failure, or if the Managed Subgraph is suspended or being deleted. When the organization's credits
run out, the error code is credits_exhausted: add credits to resume indexing.
Query it
Query the Managed Subgraph through an Endpoint Alias or its Deployment CID
with an API key that includes Subgraphs. graphops subgraphs status prints the query URL of the
Current version's Deployment CID. See Query a Subgraph.
Release a new version
Deploy again from the same project. The CLI stages the build as the Next version while the Current version keeps serving. 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
Each version you stage indexes from its start block and accrues charges alongside Current, so check that your credit balance covers both during the upgrade.
The deploy stops instead of staging in two cases:
- 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. - Another Next version is already staged. Deploy with
--replace-nextto cancel it and stage the new build, or remove it withgraphops subgraphs unstage my-subgraph.
When the Next version can be promoted, promote it. It becomes Current, and Endpoint Aliases that
target the Managed Subgraph serve it. 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.
CLI · GraphOps CLI
graphops subgraphs wait my-subgraph --for promotable --timeout 2h
graphops subgraphs promote my-subgraph
Develop and release a Subgraph explains when a Next version becomes promotable and how promotion affects your Endpoint Aliases.
Roll back
Find the Deployment CID of the release you want to return to with
graphops subgraphs history my-subgraph, which lists the Next, Current and previous versions,
newest first; graphops subgraphs status shows the most recent previous version. Deploy that CID
with --cid, which stages it as Next without building, then promote it. The staged version
indexes again from its start block, so it becomes promotable only once it has caught up, and it
accrues charges alongside Current until then.
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>
Deploy a build made elsewhere
--cid works for any Deployment CID, so you can build in one place and release from another. For
example, run graph build --ipfs in a CI build job, then
graphops subgraphs deploy my-subgraph --cid <Deployment CID> in a release job. The outcome, the
flags and the permissions are the same as when the CLI builds.
To manage a Subgraph you already deployed elsewhere, add --create to create its Managed Subgraph
from the CID. To follow the versions published to a Graph Network Subgraph ID instead, run
graphops subgraphs create my-subgraph --subgraph-id <Graph Network Subgraph ID>. See
Connect an existing Subgraph to choose between them.
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.
CLI · GraphOps CLI
# GRAPHOPS_TOKEN holds a service account API key from your CI system's secrets.
graphops subgraphs deploy my-subgraph
graphops subgraphs wait my-subgraph --for promotable --timeout 2h
graphops subgraphs promote my-subgraph
To promote exactly the build the job staged, read deploymentCid from
graphops -o json subgraphs deploy and pass it 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.
| Command | Permissions |
|---|---|
list, status, history, wait | Read Managed Subgraphs (managedSubgraphs.read) |
deploy a new version | Read Managed Subgraphs and Stage deployments (managedSubgraphs.stage) |
deploy --replace-next | Read Managed Subgraphs, Stage deployments and Cancel Next (managedSubgraphs.unstage) |
unstage | Read Managed Subgraphs and Cancel Next |
promote | Read Managed Subgraphs and Promote Next (managedSubgraphs.promote) |
deploy --create, create | Read 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.
Next steps
Last updated