graph-node: running The Graph's indexer for Ethereum subgraphs

What graph-node actually does, and who the README says it is for

The Graph is described in the README as a decentralized protocol that organizes and distributes blockchain data. Graph Node is the component that does the indexing: it reads blocks from a chain, runs the mappings of a subgraph against them, and writes the resulting entities into Postgres so they can be queried over GraphQL. The README frames subgraphs as the central mechanism for extracting and organizing blockchain data, which is why it tells you to read the official Graph documentation before touching the binary.

The stated audience is narrow and worth repeating. The guide is for subgraph developers who want to run graph-node locally to test their subgraphs during development, and for contributors who want to add features or fix bugs in graph-node itself. It is not written for someone who wants a hosted data API. If you are consuming an existing subgraph rather than authoring one, running this software is overhead you do not need.

The repository layout matches that split. The Cargo workspace lists members such as chain/ethereum, chain/near, store/postgres, server/http, server/index-node, server/json-rpc, runtime/wasm and graph. There is a separate gnd binary alongside graph-node, built by the justfile target build-all.

The indexing path from an RPC endpoint to a GraphQL query

The mechanism is visible in the command line the README gives. You pass a Postgres connection string, one or more --ethereum-rpc arguments, and an IPFS address. The ethereum-rpc argument is not a bare URL: it carries a network name and a list of provider capabilities, for example mainnet:archive,traces:https://provider.io/some/path. Those capabilities matter because a subgraph whose mappings need historical state or trace data will fail against a provider that only serves recent blocks.

IPFS is not optional in the startup command. Subgraph manifests and schemas are addressed by content hash, so the node needs a way to fetch them; the README's example points at 127.0.0.1:5001, the default local IPFS API port. Once a subgraph is deployed, queries go to the GraphQL HTTP server, which the README says listens on http://localhost:8000 by default, using routes of the form /subgraphs/name/<subgraph-name> and /subgraphs/id/<IPFS hash>.

Storage is Postgres, and the workspace has a dedicated store/postgres member plus a store/test-store member for tests. The README notes that very large instances can move to a configuration file, and that this is usually only necessary when the node connects to multiple chains or when indexing and querying are split across multiple databases. That is a real architectural boundary: a single-database local setup and a multi-chain production deployment are different operating modes, not a flag flip.

Installing graph-node and running a first indexer

The README recommends prebuilt Docker images for subgraph developers and points at ./docker/README.md for the instructions, so that is the path to take if you only want to test a subgraph. Building from source is described as usually needed only by contributors, and it requires Rust stable, PostgreSQL, IPFS and the Protobuf compiler.

If you do build from source, the database has to exist first. The README gives a psql heredoc that creates a graph user and a graph-node database, then installs three extensions: pg_trgm, btree_gist and postgres_fdw, and grants usage on the postgres_fdw foreign data wrapper to the graph role.

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

Store the connection string in an environment variable. The README suggests saving it in ~/.bashrc, and notes that psql $POSTGRES_URL is a quick way to confirm the database is reachable and the string is correct.

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

Then run the node from the repository root. GRAPH_LOG=debug is set in the README's example so startup output is verbose; the --ipfs address points at a local IPFS daemon.

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

On startup the node prints the ports it is listening on. The one you care about is the GraphQL HTTP server on http://localhost:8000. Deployment itself is not part of this repository: the README sends you to the Subgraph deployment guide and to graph-cli, and only then can you query /subgraphs/name/<subgraph-name>.

Log storage is off unless you ask for it. The README lists four backends: file (JSON Lines files, recommended for local development), Elasticsearch, Loki, and disabled as the default. The file backend needs a directory that already exists.

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

With a log backend configured, subgraph logs are queryable through the same GraphQL endpoint. The README shows a _logs query filtered by subgraphId, level and first, returning timestamp, level and text.

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

Where graph-node stops being the right tool

The most common mismatch is treating graph-node as a data source rather than an indexing engine. It does not ship blockchain data. It needs an Ethereum node or a provider, and the README explicitly leaves that choice to you: run your own node or use a provider. If your provider does not expose the capabilities a subgraph declares, indexing stalls on the blocks that need them, and nothing in the startup command will warn you in advance.

Operational weight is the second constraint. A working local instance means Postgres with three extensions, an IPFS daemon, a chain endpoint and the Rust binary. The justfile shows how much of that the test suite assumes: the _cargo-test recipe refuses to run unless THEGRAPH_STORE_POSTGRES_DIESEL_URL or GRAPH_NODE_TEST_CONFIG is set, and exits with an error otherwise. Even the project's own tests cannot start without a configured Postgres.

The third limit is scope. The README does not document rollback of a deployed subgraph, nor does it describe how to migrate an existing database between graph-node versions. Upgrades are a real cost here, and the documentation is silent on the procedure. Treat the release notes and NEWS.md as the place to look before moving a production instance.

Finally, the README does not cover multi-chain topologies beyond pointing at docs/config.md. If you need several chains in one node, you are reading a different document than the one this guide is based on.

graph-node compared with a hosted subgraph endpoint

The realistic alternative for most teams is not another self-hosted indexer but a hosted GraphQL endpoint for subgraphs, which is what The Graph's protocol layer provides. The difference is where the work sits. With a hosted endpoint you write the subgraph, deploy it, and query it; you never create a Postgres database, never run IPFS, and never pick provider capabilities. With graph-node you own all four of those pieces, and in exchange you get a local, inspectable indexer you can point at a development chain or a forked node.

That trade is why the README splits its audience. Local graph-node is the debugging loop: you change a mapping, redeploy, and query http://localhost:8000 without waiting on anyone. A hosted endpoint is the serving path. Running graph-node in production only makes sense if you specifically need to be the operator, for example to index a chain or a contract set that the hosted service does not cover.

There is also a lighter-weight option worth naming: for pure local experimentation you can skip the Rust build entirely and use the prebuilt Docker images the README recommends, which removes the toolchain and Protobuf prerequisites while keeping the Postgres and IPFS requirements.

Maintenance, releases and what the licence allows

The repository is not archived, and the last push was on 2026-08-03. That date coincides with the v0.45.0 release, following v0.44.0 on 2026-06-03 and v0.43.0 on 2026-04-23, so the cadence across those three releases is roughly six to seven weeks. The workspace version in Cargo.toml is 0.45.0, matching the newest tag.

Upgrade cost is not only the binary. The workspace pins a modern toolchain: edition 2024, and a rust-toolchain.toml at the repository root, with the README stating that the code assumes the latest available stable compiler. Rustls is pinned with the aws_lc_rs provider, and the Cargo.toml comment explains why: alloy and object_store pull in different TLS providers, so an explicit default provider must be installed before any TLS use. That is a build-level detail you inherit when you compile from source, though not when you use the Docker images.

Licensing is dual. The README says The Graph is dual-licensed under the MIT license and the Apache License, Version 2.0, and the repository carries LICENSE-MIT and LICENSE-APACHE with the workspace declaring MIT OR Apache-2.0. The README also states the software is distributed on an AS IS basis, without warranties or conditions of any kind. This is a description of what the files say, not legal advice; if you redistribute graph-node or embed it in a product, read both licence files and the NOTICE-style attribution requirements yourself.

Editorial conclusion

Adopt graph-node if you are building or debugging a subgraph and need the indexer running on your own machine, or if you intend to send patches to the Rust workspace. Do not adopt it if you only want blockchain data through a hosted GraphQL endpoint, since operating the indexer means running Postgres, IPFS and a node provider yourself. Before committing, confirm which subgraph API version your deployment targets, check that your Postgres user owns the graph-node database with the pg_trgm, btree_gist and postgres_fdw extensions created, and decide whether the default disabled log store is enough or whether you need --log-store-backend file.

Frequently asked questions

Official sources

1. Official documentation
2. Official README
3. Project repository
4. Release notes