Deploy new versions of your SubQuery project

Although you have the freedom to always upgrade and deploy new versions of your Indexing project, please be considerate during this process if your Indexing project is public to the world. Some key points to note:

If your upgrade is a breaking change, either create a new project (e.g. My SubQuery Project V2) or give your community plenty of warning of the change through social media channels.
Deploying a new SubQuery project version causes some downtime as the new version indexes the complete chain from the genesis block.

There are three methods to deploy a new version of your project to the OnFinality Indexing Service: you can use the UI, create it directly via the subql cli tool, or use an automated GitHub action.

Using the UI

Log into OnFinality’s Indexing Service and select the project you want to deploy a new version of. You can choose to either deploy to the production or staging slot. These two slots are isolated environments and each has their own databases and synchronise independently.

We recommend deploying to your staging slot only for final staging testing or when you need to resync your project data. You can then promote it to production with zero downtime. You will find testing is faster when running a project locally as you can more easily debug issues.

The staging slot is perfect for:

Final validation of changes to your Indexing project in a separate environment. The staging slot has a different URL to production that you can use in your dApps.
Warming up and indexing data for an updated Indexing project to eliminate downtime in your dApp.
Preparing a new release for your Indexing project without exposing it publicly. The staging slot is not shown to the public in the Explorer and has a unique URL that is visible only to you.

Fill in the IPFS CID of the new version of your SubQuery project codebase that you want deployed (see the documentation to publish to IPFS here. This will cause a longer downtime depending on the time it takes to index the current chain. You can always report back here for progress.

Using the CLI

Subgraph deployments are not supported in the CLI

You can also use @subql/cli to create a new deployment of your project to our Indexing Service. Please follow the guide on how to deploy a new version of your project on the OnFinality Indexing Service in the CLI documentation.

Using GitHub actions

Subgraph deployments are not supported in the with GitHub Actions

With the introduction of the deployment feature for the CLI, we've added a Default Action Workflow to the starter project in GitHub that will allow you to publish and deploy your changes automatically:

Step 1: After pushing your project to GitHub, create DEPLOYMENT environment on GitHub, and add the secret SUBQL_ACCESS_TOKEN and another secret with the name ENDPOINT which matches the RPC API endpoint that you want to connect (you can retrieve this from your project.ts and include a private API key).
Step 2: If you haven't already, create a project on OnFinality Indexing Service. This can be done using the UI or CLI.
Step 3: Once your project is created, navigate to the GitHub Actions page of your project, and select the workflow CLI deploy.
Step 4: You'll see an input field where you can enter the unique code of your project created on OnFinality’s Indexing Service. You can get the code from the URL in OnFinality’s Indexing Service. The code is based on the name of your project, where spaces are replaced with hyphens -. e.g. my project name becomes my-project-name.

Once the workflow is complete, you should be able to see your project deployed to our Indexing Service.

A common approach is to extend the default GitHub Action to automatically deploy changes to our Managed Service when code is merged into the main branch. The following change to the GitHub Action workflow do this:

YAML

on:
  push:
    branches:
      - main
jobs:
  deploy:
    name: CLI Deploy
    ...

Next Steps - Connect to your Project

Once your deployment has successfully completed and our nodes have indexed your data from the chain, you'll be able to connect to your project via the displayed GraphQL Query endpoint.

Alternatively, you can click on the three dots next to the title of your project, and view it on the Explorer. There you can use the in browser playground to get started.