Subgraph Schema Migration Helper

WHAT IT DOES

Subgraph Schema Migration Helper is a read-only developer tool that analyzes changes between current and proposed GraphQL schemas to identify migration impact. It parses both schemas, extracts entity definitions and field types, compares them to detect added, removed, or changed entities, and evaluates migration severity. The tool flags breaking changes (removed entities, removed fields, type changes), non-breaking changes (added entities, added optional fields), and provides detailed migration recommendations. It helps developers plan subgraph upgrades with minimal disruption, coordinate with frontend teams, and avoid deployment failures. By providing a clear migration impact assessment before deployment, the tool reduces risk during subgraph schema upgrades.

HOW TO USE

Connect your EVM-compatible wallet via the BGWallet bridge and select the network where your subgraph is deployed. Enter your current GraphQL schema (copy from your existing subgraph's schema.graphql file) in the "Current schema" textarea. Enter your proposed GraphQL schema (the new version you want to deploy) in the "Proposed schema" textarea. Click "Analyze Migration Impact" to compare the two schemas. Results include a summary of added, removed, and changed entities, a severity assessment (breaking/non-breaking/no changes), detailed field-level differences, and actionable migration recommendations. All analysis is read-only—no signatures or transactions are submitted.

TECHNICAL MECHANISM

The tool performs static analysis on the provided GraphQL schema strings. It parses each schema line-by-line to identify entity definitions (types with the @entity directive), extract entity names, and collect field definitions including names and types. The parser handles basic GraphQL syntax including type definitions, field declarations, and closing braces. It compares the parsed entity structures using a multi-stage diff algorithm: (1) Entity existence comparison—detecting entities that appear in one schema but not the other; (2) Field-level comparison—for entities present in both schemas, comparing field names and types to detect additions, removals, or type changes; (3) Severity classification—removed entities or changed fields are flagged as breaking changes (as they may break existing client queries), while added entities or fields are flagged as non-breaking. The tool generates a structured diff object containing added, removed, and changed entities, and produces human-readable migration recommendations including severity assessment, affected entity lists, and suggested migration steps. The analysis is purely static and does not execute any GraphQL queries or interact with Graph Node.

WHAT IT CANNOT SEE

This tool has fundamental limitations that users must understand. It cannot automatically execute schema migrations or deploy new subgraph versions—the tool is analysis-only and does not integrate with The Graph's deployment infrastructure. It cannot guarantee zero-downtime migrations without manual testing—even when no breaking changes are detected, actual deployment may affect client applications due to query patterns or indexing logic. It cannot detect all semantic breaking changes that affect client queries—changes that are not detected by simple entity/field comparison (e.g., changes in field semantics, relationship changes, or query complexity changes) can still break client applications. It cannot roll back failed migrations automatically—if a migration fails during deployment, the tool cannot revert it. It cannot analyze historical data transformation requirements without user-provided mapping logic—the tool does not generate migration scripts for transforming existing data. It cannot detect changes in event handlers or mapping logic that accompany schema changes. It cannot validate that the new schema is compatible with the existing data models and indexing logic. It cannot detect performance implications of schema changes. The tool's parser may not handle all GraphQL edge cases, including interfaces, unions, custom scalars, or directives beyond @entity.

PLEASE NOTE

This tool only supports EVM-compatible blockchains (Ethereum, Polygon, BSC, Avalanche C-Chain, Optimism, Arbitrum, and their testnets). Solana, Tron, Starknet, SUI, TON, Aptos, Bitcoin, Cosmos, and XRP are not supported. The tool is free, open-source, requires no API keys, and uses the wallet's native provider for all read operations. Always test schema migrations on a staging environment before applying to production subgraphs.