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:

Subgraph developers who want to run graph-node locally to test their Subgraphs during development
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.

bash
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:

bash
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:

bash
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):

bash
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:

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

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.