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?
- 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.
- Test on a range. Run it on a small block range with
substreams runand compare against the subgraph's entities. See how to test a Substreams package. - Choose the destination. For a SQL database, run
substreams sink postgresorclickhouseyourself, or let a Hosted Sink run it. - Keep a GraphQL surface. Enable the GraphQL layer on the Hosted Sink so your app can keep querying with GraphQL.
- 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?