goldsky-io/goldsky-agent

subgraph-migrate

Migrate a subgraph from The Graph to Goldsky as a drop-in replacement — no code changes required.

Voir la source

Mode d’emploi

  1. Copiez la commande et examinez le paquet avant de l’installer dans votre environnement agent.
  2. Consultez le document original pour les outils, identifiants et environnements requis.
  3. Décrivez les entrées et le livrable souhaité ; comparez la sortie aux sources.
npx skills add https://github.com/goldsky-io/goldsky-agent --skill subgraph-migrate

Avant de commencer

  • L’installation n’inclut ni abonnement au modèle, ni quota API, ni accès aux fichiers.
  • Étoiles et installations reflètent l’activité, pas un test indépendant de qualité ou de sécurité.
Document Skill original

Rendu depuis le dépôt source en conservant titres, exemples, code, tableaux, liens et images.

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…UseNotes
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:
graphql
  { _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.

bash
# Follow /auth-setup and run its installer with cli; Windows uses WSL.
export PATH="$HOME/.local/bin:$HOME/.goldsky/bin:$PATH"
# Have the user authenticate manually in this same environment.
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:

bash
# From a public GraphQL endpoint
goldsky subgraph deploy my-subgraph/1.0.0 --from-url <your-thegraph-endpoint>

# From an IPFS hash (deployment ID)
goldsky subgraph deploy my-subgraph/1.0.0 --from-ipfs-hash <Qm...>

# From source (build first per /subgraph-builder)
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

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

graphql
{ _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:

bash
goldsky subgraph tag create my-subgraph/1.0.0 --tag prod
# Tagged endpoint:
# https://api.goldsky.com/api/public/<project-id>/subgraphs/my-subgraph/prod/gn

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

Tâches connexes

du même dépôt

Autres Skills

Tous les Skills
goldsky-io
Communauté

auth-setup

Set up Goldsky CLI authentication and project configuration. Use this skill when the user needs to: install the goldsky CLI (what's the official install command?), run goldsky login (including when the browser opens but 'authentication failed'), run goldsky project list and see 'not logged in' or 'unauthorized', switch between Goldsky projects, check which project they're currently authenticated to, or fix 'unauthorized' errors when running goldsky turbo commands. Also use for 'walk me through s

Installations / 1h
4
GitHub Stars
12
Mis à jour
2 nov.
goldsky-io
Communauté

boost

Configure and troubleshoot Goldsky Boost, the free RPC caching CDN in front of a provider the user already pays for. Use for cutting RPC bills without migrating, connecting Alchemy/QuickNode/Infura upstreams, goldsky boost, edge.goldsky.com/boost, verification, cache hit rates, ethgetLogs forwarding, and x-cache / x-edge-billable / x-edge-source headers. Boost keeps the existing provider and forwards uncached requests. To replace a provider with Goldsky's managed RPC, use /edge. Pipeline, Subgra

Installations / 1h
4
GitHub Stars
12
Mis à jour
2 nov.
goldsky-io
Communauté

datasets

Use this skill when the user needs to look up or verify Goldsky blockchain dataset names, chain prefixes, dataset types, or versions. Triggers on questions like 'what\\'s the dataset name for X?', 'what prefix does Goldsky use for chain Y?', 'what version should I use for Z?', or 'what datasets are available for Solana/Stellar/Arbitrum/etc?'. Also use for chain-specific dataset questions (e.g., polygon vs matic prefix, stellarnet balance datasets, solana token transfer dataset names), and to ans

Installations / 1h
4
GitHub Stars
12
Mis à jour
2 nov.
goldsky-io
Communauté

edge

Configure and troubleshoot Goldsky Edge, Goldsky's managed EVM RPC endpoint service. Use for Edge RPC, Goldsky RPC endpoints, edge.goldsky.com, slow ethgetLogs, rate limits, hedged requests, flashblocks, HyperEVM system transactions, x402 pay-per-request RPC, pricing, the Edge dashboard, gsedge keys, rpc-edge, and errors -32005/-32012/-32014/-32015/-32016. Covers resilient low-latency EVM endpoints and provider comparisons. For self-hosted eRPC configuration, consult docs.erpc.cloud/llms.txt. To

Installations / 1h
4
GitHub Stars
12
Mis à jour
2 nov.