Subgraph Versioning

Overview

Satsuma allows you to deploy different subgraphs and subgraph versions.

• Each subgraph has a live version, which serves traffic at a static endpoint:

  https://subgraph.satsuma-prod.com/<ORGANIZATION>/<SUBGRAPH NAME>/api

• A subgraph can have up to 5 versions, which have version-specific endpoints:

  https://subgraph.satsuma-prod.com/<ORGANIZATION>/<SUBGRAPH NAME>/version/<VERSION NAME>/api

• Version names must be unique within a subgraph.

• Satsuma will randomly generate a version name when deploying from versions of the CLIs that don't support the --version-label flag.

Promoting a version to live

When deploying a new subgraph, the first version will be set to live.

However, new versions of existing subgraphs will not be automatically promoted to live. You can promote the version to live within the dashboard.

API endpoint

You can also set a version to live via an API call:

curl -X POST https://subgraphs.alchemy.com/api/subgraphs/<ORGANIZATION>/<SUBGRAPH_NAME>/<VERSION_NAME>/promote-live \
	-H 'x-api-key: <DEPLOY_KEY>'

Use cases

This flexible system allows you to do things like:

• Test a new version with live queries before switching your application over.

• Instantly roll back to a previous version if there are issues with a new version.

Auto-promote

In certain situations, you might want to auto-promote a newly deployed version. Once the subgraph version finishes syncing, it will automatically get promoted to live.

This can be useful within your CI / CD pipelines.

API endpoint

Make a request to this endpoint to enable auto-promote for a subgraph version:

curl -X POST https://subgraphs.alchemy.com/api/subgraphs/<ORGANIZATION>/<SUBGRAPH_NAME>/<VERSION_NAME>/auto-promote-live \
	-H "Content-Type: application/json" -H "x-api-key: <DEPLOY_KEY>"