Subgraph management
The Graph is spreading across the Internet and it is used with a lot of different projects.
At some point it may be required to manage deployed subgraphs. It is generally related to the cases:
- Deploy subgraph
- Deploy new version of subgraph - the old one will remain in the list and database
- Reassign subgraph to a different index node
- Pause indexing subgraph - subgraph will remain in the list and database
For this, we can use the following approaches
Graph CLI
The Graph CLI (graph-cli) is a tool for subgraph build and deployment
# Install graph-cli
yarn global add @graphprotocol/graph-cli
# Install dependencies
yarn install
# Codegen
yarn codegen
# Build
yarn build
# Graph create
graph create ${SUBGRAPH_NAME} \
--node ${INDEX_NODE_ENDPOINT} \
# Graph deploy
graph deploy ${SUBGRAPH_NAME} \
--version-label ${GITHUB_REF_NAME} \
--node ${INDEX_NODE_ENDPOINT} \
--ipfs ${IPFS_ENDPOINT}
Graph node API
We can find in graph-node/server/json-rpc/src/lib.rs defined 4 methods
subgraph_create
subgraph_deploy
subgraph_remove
subgraph_reassign
And we can interact with the Graph node JSON-RPC using the port set by --admin-port option which is by default 8020 and use different HTTP clients like httpie and curl
# Debian
apt install httpie curl
# RHEL
yum install httpie curl
# Python
pip install httpie
Create subgraph deployment
# httpie
http post index-node:8020 \
jsonrpc=2.0 \
id=2 \
method=subgraph_create \
params:='{"name": "indexer-agent/ke3y2c7Kai"}'
# curl
curl -X POST index-node:8020 \
-H 'Content-Type: application/json' \
-d '{"jsonrpc": "2.0", "id": "2", "method": "subgraph_create", "params": {"name": "indexer-agent/ke3y2c7Kai"}}'
Deploy subgraph
# httpie
http post index-node:8020 \
jsonrpc=2.0 \
id=2 \
method=subgraph_deploy \
params:='{"name": "indexer-agent/ke3y2c7Kai", "ipfs_hash": "QmWK7Phe4L6H3dzXHh48G1TrYDugeAVaFroUke3y2c7Kai"}'
# curl
curl -X POST index-node:8020 \
-H 'Content-Type: application/json' \
-d '{"jsonrpc": "2.0", "id": "2", "method": "subgraph_deploy", "params": {"name": "indexer-agent/ke3y2c7Kai", "ipfs_hash": "QmWK7Phe4L6H3dzXHh48G1TrYDugeAVaFroUke3y2c7Kai"}}'
Reassign subgraph
# httpie
http post index-node:8020 \
jsonrpc=2.0 \
id=2 \
method=subgraph_reassign \
params:='{"ipfs_hash": "QmWK7Phe4L6H3dzXHh48G1TrYDugeAVaFroUke3y2c7Kai", "node_id": "index_node_2"}'
# curl
curl -X POST index-node:8020 \
-H 'Content-Type: application/json' \
-d '{"jsonrpc": "2.0", "id": "2", "method": "subgraph_reassign", "params": {"ipfs_hash": "QmWK7Phe4L6H3dzXHh48G1TrYDugeAVaFroUke3y2c7Kai", "node_id": "index_node_2"}}'
Pause subgraph
Assign to non-existing node id
# httpie
http post index-node:8020 \
jsonrpc=2.0 \
id=2 \
method=subgraph_reassign \
params:='{"ipfs_hash": "QmWK7Phe4L6H3dzXHh48G1TrYDugeAVaFroUke3y2c7Kai", "node_id": "paused"}'
# curl
curl -X POST index-node:8020 \
-H 'Content-Type: application/json' \
-d '{"jsonrpc": "2.0", "id": "2", "method": "subgraph_reassign", "params": {"ipfs_hash": "QmWK7Phe4L6H3dzXHh48G1TrYDugeAVaFroUke3y2c7Kai", "node_id": "paused"}}'
Resume subgraph
Assign to an existing node id
# httpie
http post index-node:8020 \
jsonrpc=2.0 \
id=2 \
method=subgraph_reassign \
params:='{"ipfs_hash": "QmWK7Phe4L6H3dzXHh48G1TrYDugeAVaFroUke3y2c7Kai", "node_id": "index_node_2"}'
# curl
curl -X POST index-node:8020 \
-H 'Content-Type: application/json' \
-d '{"jsonrpc": "2.0", "id": "2", "method": "subgraph_reassign", "params": {"ipfs_hash": "QmWK7Phe4L6H3dzXHh48G1TrYDugeAVaFroUke3y2c7Kai", "node_id": "index_node_2"}}'
Remove subgraph
# httpie
http post index-node:8020 \
jsonrpc=2.0 \
id=2 \
method=subgraph_remove \
params:='{"name": "indexer-agent/ke3y2c7Kai", "ipfs_hash": "QmWK7Phe4L6H3dzXHh48G1TrYDugeAVaFroUke3y2c7Kai"}'
# curl
curl -X POST index-node:8020 \
-H 'Content-Type: application/json' \
-d '{"jsonrpc": "2.0", "id": "2", "method": "subgraph_remove", "params": {"name": "indexer-agent/ke3y2c7Kai", "ipfs_hash": "QmWK7Phe4L6H3dzXHh48G1TrYDugeAVaFroUke3y2c7Kai"}}'
Will remove the mapping from the given name to the underlying deployment. If no other subgraph name uses that deployment, it becomes eligible for removal, and the steps for removing unused deployments will delete its data.
Graphman
The graphman command is included in the official containers, and we can docker exec into our graph-node container to run it. It requires a configuration file. For more information please see Common maintenance tasks.
-
Login to the graph node container
-
Create config file
cat << EOF > graph-node.toml [store] [store.primary] connection = "postgresql://$postgres_user:$postgres_pass@$postgres_host:$postgres_port/$postgres_db" pool_size = 3 [deployment] [[deployment.rule]] store = "primary" indexers = [ "default" ] [chains] ingestor = "default" EOF -
Get information about subgraph
graphman --config graph-node.toml info indexer-agent/ke3y2c7Kai -
Unregister a subgraph name with a Graph node
graphman --config graph-node.toml remove indexer-agent/ke3y2c7Kai -
Compiles a list of unused deployments
graphman --config graph-node.toml unused record -
Inspect the list
graphman --config graph-node.toml unused list -e -
Remove the deployments that have previously marked for removal
graphman --config graph-node.toml unused remove -
Reassign subgraph
graphman --config graph-node.toml reassign QmWK7Phe4L6H3dzXHh48G1TrYDugeAVaFroUke3y2c7Kai index_node_2 -
Pause subgraph
graphman --config graph-node.toml reassign QmWK7Phe4L6H3dzXHh48G1TrYDugeAVaFroUke3y2c7Kai paused -
Resume subgraph
graphman --config graph-node.toml reassign QmWK7Phe4L6H3dzXHh48G1TrYDugeAVaFroUke3y2c7Kai index_node_1