subgraph-migrate

The Graph からサブグラフを移行する

既存のサブグラフを The Graph から Goldsky に移行するのは、そのまま置き換えるだけです。サブグラフのコードを変更する必要はありません。公開済みのサブグラフ（URL または IPFS ハッシュ）を Goldsky に指定するか、ソースから再デプロイして、アプリがクエリするエンドポイントを切り替えます。

まず、サブグラフが本当にまだ必要か、簡単に確認しましょう。 移行は、必要性を見直すよい機会です。dApp にホストされた GraphQL API が必要なら、サブグラフの移行が適切です。以下の手順に進んでください。一方、実際の目的が分析やバックエンド用にデータベースへデータを取り込むことなら、Turbo パイプラインのほうが高速で、信頼性が高く、低コストです（/turbo-builder）。そもそもサブグラフが不要な場合もあります。この点は一度だけ伝え、GraphQL が明らかに必要であれば移行を進めてください。

対象範囲

• このスキルの対象は、The Graph（ホステッドサービス、Subgraph Studio、または分散型ネットワーク）からの移行です。
• 移行後にサブグラフのデプロイや同期が失敗する場合の診断には、/subgraph-doctor を使用してください。
• デプロイ、タグ、エンドポイント、Webhook のリファレンスには、/subgraph-builder を使用してください。
• Alchemy から移行する場合は、専用の Alchemy 移行ドキュメントに従ってください（ここでは扱いません）。

厳守するルール 2 つ

1. ソース URL または IPFS ハッシュを絶対に捏造しないでください。 必ずユーザーに実際のデプロイ URL または IPFS ハッシュを提示してもらってください。api.thegraph.com/... やゲートウェイ URL を組み立てたり推測したりしないでください。ソース URL の捏造は、失敗の主な原因となり、デプロイの試行を無駄にします。確認済みのソースがない場合は、ユーザーに尋ねてください（ステップ 2 を参照）。

2. 料金について絶対に言及しないでください。 移行が「無料」または「安い」と伝えたり、料金を見積もったりしないでください。サブグラフの料金は使用状況やプランによって異なり、誤った推測は信頼を損ないます（ある顧客は「安い」と言われた後に、1 万ドル超の見積もりを提示されました）。費用に関する質問は、Goldsky の見積もり窓口（[email protected]）または担当のアカウント窓口／営業担当者に案内してください。

ステップ 1：移行方法を選ぶ

手元にあるもの…	使用するもの	備考
デプロイ済みサブグラフの公開 GraphQL エンドポイント	--from-url <url>	最も簡単です。公開されているサブグラフで利用できます。
サブグラフの IPFS ハッシュ（デプロイ ID）	--from-ipfs-hash <hash>	ハッシュはあるものの、クエリ可能な URL がない場合に使用します。
手元にある元のソースコード	--path .（先にビルド）	公開済みバージョンが利用できない場合や、コードを変更したい場合に使用します。

ユーザーが動作するエンドポイントを持っている場合は --from-url を推奨してください。そうでなければ --from-ipfs-hash を推奨してください。

ステップ 2：実際のソース識別子を取得する

デプロイする前に、ユーザーから実際のソースを取得してください。推測してはいけません。

• URL からの移行： The Graph で現在クエリしている GraphQL エンドポイントを貼り付けるよう、ユーザーに依頼してください。
• IPFS ハッシュからの移行： IPFS ハッシュはデプロイ ID（Qm...）です。ユーザーは The Graph のエクスプローラー／Studio で確認するか、既存のエンドポイントにクエリして取得できます。

  { _meta { deployment } }
  

  deployment は IPFS ハッシュです。

どちらも提示できない場合は、ソースからのデプロイ（--path）に切り替え、init／ビルドの手順について /subgraph-builder を案内してください。

ステップ 3：CLI をインストールしてログインする

CLI のセットアップは、移行で最もつまずきやすい箇所です。デプロイ前に確認してください。

# 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

goldsky project list を実行して確認します。ログインに失敗した場合は、/auth-setup を使用してください。

ステップ 4：Goldsky にデプロイする

ステップ 1 で選んだ移行方法に合う行を選んでください。Goldsky のデプロイには、任意の name/version を指定します。

# 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

同じ IPFS ハッシュのサブグラフがすでに Goldsky でインデックス化されている場合、同期が瞬時に 100% まで完了することがあります。これは想定どおりであり、エラーではありません。独自のレート制限が適用される専用エンドポイントは引き続き利用できます。

メタデータが大量にあるデプロイでは、IPFS のタイムアウト（524）が発生することがあります。その場合は再試行してください。通常は後の試行で成功します。失敗が続く場合は、手動で移行してもらうためサポートにエスカレーションしてください。

ステップ 5：同期を確認する

goldsky subgraph list my-subgraph/1.0.0

次に、新しい Goldsky エンドポイントに対して_metaクエリを実行し、インデックス済みのヘッドが進んでいることを確認します。

{ _meta { hasIndexingErrors block { number } } }

• 事前にインデックスされていない新しいマイグレーションは、開始ブロックから同期されます。完了まで時間がかかることがありますが、これは正常です。
• 低い割合で止まっている（例：0.05％）場合、通常はマッピング／ハンドラーのエラーかネットワークの誤りが原因であり、同期が遅いわけではありません。/subgraph-doctorに引き継いでください。
• hasIndexingErrors: trueの場合は、/subgraph-doctorに引き継いでください。

ステップ 6：タグを移行してエンドポイントを切り替える

Goldskyのタグを使うと、安定したエイリアス（prodなど）をバージョンに固定できるため、再デプロイしてもフロントエンドのURLが変わりません。

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

同期が完了したら、アプリの接続先をGoldskyエンドポイントに切り替えます（今後の再デプロイでフロントエンドに影響が出ないよう、タグ付きURLを使用してください）。エンドポイント、プライベートエンドポイント／APIキー、ウェブフックについては、/subgraph-builderを参照してください。

よくある移行時の問題

The Graph向けに作成されたサブグラフを初めてデプロイする際に、Goldskyの仕様検証で問題が発生することがあります。次の問題が発生した場合は、エラーの全文を/subgraph-doctorに引き継いでください。

• subgraph must use a single apiVersion across its data sources — apiVersionを統一してください。
• Interface '<X>' not defined、またはタイムシリーズ／集計の仕様エラー — スキーマを修正してください。
• no network <slug> found — Goldskyではチェーンのスラッグが異なります。サポート対象ネットワークの正しいスラッグを使用してください。
• A deployment with this name & version already exists — バージョンを上げてください。
• 有効なサブグラフでもCLIのデプロイが失敗し続ける場合 — ノーコード／ダッシュボードからのデプロイを代替手段として利用してください。両方失敗する場合はエスカレーションしてください。

関連項目

• /subgraph-builder — サブグラフの構築、作成、デプロイ。エンドポイント、タグ、ウェブフックのリファレンス
• /subgraph-doctor — 移行後にデプロイまたは同期に失敗するサブグラフの診断
• /auth-setup — CLIのインストールとログイン
• Goldskyのドキュメント： docs.goldsky.com/subgraphs/migrate-from-the-graph