📋 Process of making changes to the supergraph
Run schema checks.
Deploy code changes.
Publish the new subgraph schema to GraphOS.
📋 Step 1: Schema checks
Schema checks are a set of predefined tests that help identify potential failures caused by schema updates. They check for issues like incompatibilities between subgraph schemas or breaking existing client operations. With schema checks, we can ensure that our schema changes won't cause issues when we deploy to production.
Types of schema checks:
- Build checks validate that a subgraph's schema changes can still compose successfully with other subgraph schemas in the supergraph.
- Operation checks validate that a schema's changes won't break any operations that existing clients send to the graph.
- Linter checks analyze your proposed schema changes for violations of formatting rules and other GraphQL best practices. You can see the full list of default rules in the Apollo documentation.
rover subgraph check
Using the Rover CLI, we can run schema checks locally in our terminal or we can integrate schema checks into our CI pipelines to run automatically against new pull requests.
rover subgraph check <GRAPH_REF> \--schema <SCHEMA_FILE_PATH> \--name <SUBGRAPH_NAME>
Note: The GRAPH_REF refers to the graph reference, which identifies our supergraph in GraphOS. A graph ref starts with the graph's ID, followed by an @ symbol, followed by the graph variant.
This command first runs a build check, then an operation check, then a linter check, and finally outputs the results in the command line. It also reports the results to Studio, so we can view them from our graph's Checks page.
📋 Step 2: Deploy code changes
This step looks different for all projects. In this workshop, we've set up automatic deploys to Railway (or your hosting platform of choice) when new commits are pushed to the main branch on GitHub.
📋 Step 3: Publishing the subgraph schema
The GraphOS schema registry needs to know about our schema updates! To do so, we need to publish our subgraph schema to the registry.
rover subgraph publish
Similar to schema checks, there are two main ways to publish a subgraph schema using the Rover CLI: locally, or in CI pipelines.
rover subgraph publish <GRAPH_REF> \--schema <SCHEMA_FILE_PATH> \--name <SUBGRAPH_NAME>
GraphOS launch
A launch represents the complete process of applying a set of updates to a supergraph. A launch is triggered when a new or updated version of a subgraph schema is published, when a new subgraph is added, or when the router configuration is changed.
