Back to Common Questions

Common Questions / Choosing an approach

How do I migrate from a subgraph to Substreams?

Updated

You rebuild the extraction and transformation logic as a Substreams module graph, point a sink at your own database, and optionally serve the result over GraphQL. You do not start from zero: the open-source agent skills, including substreams-convert, do most of the port from your existing subgraph.

Why migrate?

Teams usually move when the subgraph model stops fitting:

  • Sync times. Subgraphs process history block by block. Substreams parallelises it — see the benchmark.
  • Throughput. High-volume chains and heavy transformations.
  • Destinations. Postgres, ClickHouse, files, or a stream, not just a single GraphQL endpoint.
  • State patterns. Account-level state tracking that a linear subgraph handles poorly.

If none of those hurt, a subgraph may be fine. See Subgraph vs API.

What are the steps?

  1. Port the logic. Give a coding agent that has the Substreams skills your subgraph (manifest, schema, mappings) and have it generate a Substreams package with typed protobuf outputs.
  2. Test on a range. Run it on a small block range with substreams run and compare against the subgraph's entities. See how to test a Substreams package.
  3. Choose the destination. For a SQL database, run substreams sink postgres or clickhouse yourself, or let a Hosted Sink run it.
  4. Keep a GraphQL surface. Enable the GraphQL layer on the Hosted Sink so your app can keep querying with GraphQL.
  5. Backfill and cut over. Backfill with extra workers (how), verify, then switch your app.

What changes for my app?

The query endpoint and key change: Hosted Sink GraphQL authenticates with an API key from The Graph Market rather than a subgraph query key. Field names follow your database tables rather than subgraph entities, so expect to adjust queries.


Frequently asked questions

Do I need to write Rust? Not necessarily. See Can I build a Substreams package without knowing Rust?

Can I keep my subgraph running during the move? Yes. The two are independent, so you can run both and compare before cutting over.


Get an API key at thegraph.market.

Related: Why is my subgraph syncing so slow? · What are the Substreams agent skills? · What is Substreams?