Developer onboarding
Deploying Subgraphs
The first step in developing a subgraph is to create the subgraph manifest and to generate code for the subgraph by installing the Graph CLI. Once you have accomplished this, you can then deploy your subgraph in the next step.
1. Creating a Graph Explorer account.
To use Subgraph Studio, you need an account in The Graph Explorer. Signing up is a seamless process as you can use your Github account.
2. Storing the Access Token.
Once you are registered with The Graph’s Explorer, move to your account’s dashboard. To store the access token of your dashboard on your computer, copy the access token that is displayed. Then, run the following command:
This is not a mandatory step for each new session. Just keep in mind that you have would have to repeat this process when you generate a new access token.
3. Creating the Subgraph
The last step before you are ready to deploy your subgraph is to add your subgraph to The Graph Explorer. You can do this by navigating to the dashboard and clicking “Add Subgraph.”
On others left now is to safe and create your new subgraph. You will be followed up with instructions that guides you through installing the Graph CLI and defining your subgraph. Both topics are covered in the previous guide on defining subgraphs. The other instructions listed is about deploying your subgraph, which we will have a look at the following.
4. Deploying Your Subgraph.
The process of deploying your subgraph is straightforward. Simply run the command yarn deploy to deploy your subgraph. What this does is to upload the subgraph’s files to IPFS with yarn build. It will also notify The Graph Explorer so that it starts indexing your subgraph.
New Ethereum blocks will continuously be inspected by The Graph Node as these blocks are mined.
5. Redeploying your subgraph.
Keep in mind that you will have to redeploy your subgraph whenever you make changes to its definition (i.e. its entity mappings etc.). To do so, run the command yarn deploy. This will get the updated version of subgraph redeployed. Depending on how many blocks have been added to the chain, the process of redeploying your subgraph could take some time. This is because The Graph Node with have to start reindexing the entire subgraph starting at the genesis block.
The newly deployed version of your subgraph will immediately replace a previously deployed subgraph that is still Syncing. If the synchronization process has already finished, the newly deployed version of your subgraph will be marked as Pending Version. Once syncing has finished, the new version will replace the old one. This will allow you to keep your services live while you are synchronizing the new version.
A) Deploying your subgraph to multiple Ethereum networks
Deploying one subgraph to multiple ETH networks without duplicating its code is a challenge, as contract addresses for each network are different. You can address this challenge by using a templating system, for example. This will enable you to parameterize aspects like contract addresses.
This is how you would go ahead if you wanted to deploy a subgraph to the Ethereum mainnet but also to ropsten by creating two config files that provide the addresses for each network:
Next, you will have to use the variable placeholders {{address}} and {{network}} to subsitute the substitute the network addresses and name in your subgraph’s manifest. After this, rename the manifest, for example to: subgraph.template.yaml:
If you want to generate a manifest to both networks, these are the two additional commands you will have to add to package.json with a dependency on mustache:
After this, you can deploy your subgraph to either the mainnet or to Ropsten, use one of the two commands:
If you want to see an example of how this all works, have a look at this.
6. Checking the health of your subgraph.
The best sign of a healthy subgraph is that it has successfully synchronized. Along the road, it’s possible that new triggers on the blockchain cause issues. These issues could be untested error conditions but also issues with performance or node operators.
To check the health of your subgraph, you can query a GraphQL endpoint that the Graph Node exposes. To check of the status of the current version of your subgraph, you can use this sample query:
If you want to reference the full schema for this endpoint, you can find it here.
The sample query will provide you the chainHeadBlock. You can use this to compare it with the latestBlock to see it’s status and whether or not it’s running behind. The three outputs synced, healthy, failed and fatalError inform you about the state of the subgraph.
