| name | subgraph-migrate |
| description | Migrate a subgraph from The Graph to Goldsky as a drop-in replacement — no code changes required. Use this skill when the user wants to move, switch, port, or migrate a subgraph off The Graph (hosted service, Subgraph Studio, or the decentralized network) onto Goldsky, or when a subgraph endpoint they relied on (e.g. The Graph hosted service) was sunset. Triggers on: 'migrate from The Graph', 'move my subgraph to Goldsky', 'switch off The Graph', 'redeploy a TheGraph subgraph', 'my subgraph endpoint is gone', 'from-url', 'from-ipfs-hash', 'drop-in replacement for The Graph'. For diagnosing a subgraph that fails after migrating, use /subgraph-doctor. For building/authoring or general deploy/tag/endpoint reference, use /subgraph-builder. |
Migrate a Subgraph from The Graph
Migrating an existing subgraph from The Graph to Goldsky is a drop-in replacement — you don't change your subgraph code. You point Goldsky at your published subgraph (by URL or IPFS hash) or redeploy from source, then swap the endpoint your app queries.
Worth a quick check first: do they still need a subgraph?
Migration is a natural moment to reconsider. If the dApp needs a hosted GraphQL API, migrating the subgraph is the right move — continue below. But if the real goal is getting this data into a database for analytics or a backend, a Turbo pipeline is faster, more reliable, and cheaper (/turbo-builder) — they may not need a subgraph at all. Surface this once; if they clearly want GraphQL, proceed with the migration.
Boundaries
- This skill is for migrating from The Graph (hosted service, Subgraph Studio, or decentralized network).
- For diagnosing a subgraph that fails to deploy or sync after migrating, use
/subgraph-doctor.
- For deploy/tag/endpoint/webhook reference, use
/subgraph-builder.
- For migrating from Alchemy, follow the dedicated Alchemy migration docs (not covered here).
Two hard rules
1. Never invent the source URL or IPFS hash. Always have the user provide their actual deployment URL or IPFS hash. Do not construct or guess api.thegraph.com/... or gateway URLs — fabricated source URLs are a top failure mode and waste deploy attempts. If you don't have a verified source, ask for it (see Step 2).
2. Never quote pricing. Do not tell the user migration is "free" or "cheap" or estimate a price. Subgraph pricing depends on usage and plan, and a wrong guess erodes trust (one customer was told "cheap" then quoted $10k+). For any cost question, route them to a Goldsky quote: support@goldsky.com or their account/sales contact.
Step 1: Choose a migration path
| You have… | Use | Notes |
|---|
| A public GraphQL endpoint for the deployed subgraph | --from-url <url> | Simplest. Works for publicly deployed subgraphs. |
| The subgraph's IPFS hash (deployment ID) | --from-ipfs-hash <hash> | Use when you have the hash but not a queryable URL. |
| The original source code locally | --path . (build first) | Use if the published version is unavailable or you want to change code. |
Recommend --from-url when the user has a working endpoint; otherwise --from-ipfs-hash.
Step 2: Get the real source identifier
Before deploying, get the user's actual source — do not guess it.
- From-URL: Ask the user to paste the GraphQL endpoint they currently query on The Graph.
- From-IPFS-hash: The IPFS hash is the deployment ID (
Qm...). The user can find it on The Graph's explorer/Studio, or by querying their existing endpoint:
{ _meta { deployment } }
deployment is the IPFS hash.
If the user can't produce either, fall back to deploying from source (--path) and point them to /subgraph-builder for init/build.
Step 3: Install the CLI and log in
CLI setup is the most common migration sticking point — confirm it before deploying.
curl https://goldsky.com | sh
npm i -g @goldskycom/cli
goldsky login
Verify with goldsky project list. If login fails, use /auth-setup.
Step 4: Deploy to Goldsky
Pick the line matching the path from Step 1. Choose your own name/version for the Goldsky deployment:
goldsky subgraph deploy my-subgraph/1.0.0 --from-url <your-thegraph-endpoint>
goldsky subgraph deploy my-subgraph/1.0.0 --from-ipfs-hash <Qm...>
goldsky subgraph deploy my-subgraph/1.0.0 --path ./build
If a subgraph with the same IPFS hash was already indexed on Goldsky, it can sync instantly to 100% — that's expected, not an error. You still get your own endpoint with your own rate limits.
Deployments with a lot of metadata can hit IPFS timeouts (524). Retry — usually a later attempt succeeds. If it keeps failing, escalate to support to port it manually.
Step 5: Verify it's syncing
goldsky subgraph list my-subgraph/1.0.0
Then run the _meta query against the new Goldsky endpoint to confirm the indexed head is advancing:
{ _meta { hasIndexingErrors block { number } } }
- A fresh migration that wasn't pre-indexed syncs from the start block — this can take a while. That's normal.
- Stuck at a low % (e.g. 0.05%) is usually a mapping/handler error or a wrong network, not a slow sync. Hand off to
/subgraph-doctor.
hasIndexingErrors: true → /subgraph-doctor.
Step 6: Migrate tags and swap your endpoint
Goldsky tags pin a stable alias (like prod) to a version so your frontend URL never changes on redeploy:
goldsky subgraph tag create my-subgraph/1.0.0 --tag prod
Once synced, point your app at the Goldsky endpoint (use the tagged URL so future redeploys don't break the frontend). See /subgraph-builder for endpoints, private endpoints/API keys, and webhooks.
Common migration gotchas
These show up because a subgraph authored for The Graph hits Goldsky's spec validation on first deploy. If any occur, hand the exact error to /subgraph-doctor:
subgraph must use a single apiVersion across its data sources — unify apiVersion.Interface '<X>' not defined, or timeseries/aggregation spec errors — fix the schema.no network <slug> found — the chain slug differs on Goldsky; use the correct supported-network slug.A deployment with this name & version already exists — bump the version.- CLI deploy keeps failing on a valid subgraph — the no-code/dashboard deploy path is a fallback; escalate if both fail.
Related
/subgraph-builder — Build, author, and deploy subgraphs; endpoints, tags, webhooks reference/subgraph-doctor — Diagnose a subgraph that fails to deploy or sync after migrating/auth-setup — CLI installation and login- Goldsky docs: docs.goldsky.com/subgraphs/migrate-from-the-graph
