Subgraph management
The Graph project is spreading across the Internet and it is used with a lot of 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 approached
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 –admin-port 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 nonexistent 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 your 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