Graph Node

Overview

The Graph is a decentralized protocol that organizes and distributes blockchain data across the leading Web3 networks. A key component of The Graph's tech stack is Graph Node.

Before using graph-node, it is highly recommended that you read the official Graph documentation to understand Subgraphs, which are the central mechanism for extracting and organizing blockchain data.

This guide is for:

1. Subgraph developers who want to run graph-node locally to test their Subgraphs during development
2. Contributors who want to add features or fix bugs to graph-node itself

Running graph-node from Docker images

For subgraph developers, it is highly recommended to use prebuilt Docker images to set up a local graph-node environment. Please read these instructions to learn how to do that.

Running graph-node from source

This is usually only needed for developers who want to contribute to graph-node.

Prerequisites

To build and run this project, you need to have the following installed on your system:

• Rust (latest stable): Follow How to install Rust. Run rustup install stable in this directory to make sure all required components are installed. The graph-node code assumes that the latest available stable compiler is used.
• PostgreSQL: PostgreSQL Downloads lists downloads for almost all operating systems.
  • For OSX: We highly recommend Postgres.app.
  • For Linux: Use the Postgres version that comes with the distribution.
• IPFS: Installing IPFS
• Protobuf Compiler: Installing Protobuf

For Ethereum network data, you can either run your own Ethereum node or use an Ethereum node provider of your choice.

Create a database

Once Postgres is running, you need to issue the following commands to create a database and configure it for use with graph-node.

The name of the SUPERUSER depends on your installation, but is usually postgres or your username.

psql -U <SUPERUSER> <<EOF
create user graph with password '<password>';
create database "graph-node" with owner=graph template=template0 encoding='UTF8' locale='C';
create extension pg_trgm;
create extension btree_gist;
create extension postgres_fdw;
grant usage on foreign data wrapper postgres_fdw to graph;
EOF

For convenience, set the connection string to the database in an environment variable, and save it, e.g., in ~/.bashrc:

export POSTGRES_URL=postgresql://graph:<password>@localhost:5432/graph-node

Use the POSTGRES_URL from above to have graph-node connect to the database. If you ever need to manually inspect the contents of your database, you can do that by running psql $POSTGRES_URL. Running this command is also a convenient way to check that the database is up and running and that the connection string is correct.

Build and Run graph-node

Clone this repository and run this command at the root of the repository:

export GRAPH_LOG=debug
cargo run -p graph-node --release -- \
  --postgres-url $POSTGRES_URL \
  --ethereum-rpc NETWORK_NAME:[CAPABILITIES]:URL \
  --ipfs 127.0.0.1:5001

The argument for --ethereum-rpc contains a network name (e.g. mainnet) and a list of provider capabilities (e.g. archive,traces). The URL is the address of the Ethereum node you want to connect to, usually a https URL, so that the entire argument might be mainnet:archive,traces:https://provider.io/some/path.

When graph-node starts, it prints the various ports that it is listening on. The most important of these is the GraphQL HTTP server, which by default is at http://localhost:8000. You can use routes like /subgraphs/name/<subgraph-name> and /subgraphs/id/<IPFS hash> to query subgraphs once you have deployed them.

Deploying a Subgraph

Follow the Subgraph deployment guide. After setting up graph-cli as described, you can deploy a Subgraph to your local Graph Node instance.

Advanced Configuration

The command line arguments generally are all that is needed to run a graph-node instance. For advanced uses, various aspects of graph-node can further be configured through environment variables.

Very large graph-node instances can also be configured using a configuration file That is usually only necessary when the graph-node needs to connect to multiple chains or if the work of indexing and querying needs to be split across multiple databases.

Log Storage

graph-node supports storing and querying subgraph logs through multiple backends:

• File: Local JSON Lines files (recommended for local development)
• Elasticsearch: Enterprise-grade search and analytics (for production)
• Loki: Grafana's log aggregation system (for production)
• Disabled: No log storage (default)

Quick example (file-based logs for local development):

mkdir -p ./graph-logs

cargo run -p graph-node --release -- \
  --postgres-url $POSTGRES_URL \
  --ethereum-rpc mainnet:archive:https://... \
  --ipfs 127.0.0.1:5001 \
  --log-store-backend file \
  --log-store-file-dir ./graph-logs

Logs are queried via GraphQL at http://localhost:8000/graphql:

query {
  _logs(subgraphId: "QmYourSubgraphHash", level: ERROR, first: 10) {
    timestamp
    level
    text
  }
}

For complete documentation, see the Log Store Guide, which covers:

• How to configure each backend (Elasticsearch, Loki, File)
• Complete GraphQL query examples
• Choosing the right backend for your use case
• Performance considerations and best practices

Contributing

Please check CONTRIBUTING.md for development flow and conventions we use. Here's a list of good first issues.

License

Copyright © 2018-2019 Graph Protocol, Inc. and contributors.

The Graph is dual-licensed under the MIT license and the Apache License, Version 2.0.

Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either expressed or implied. See the License for the specific language governing permissions and limitations under the License.