Overview
We've seen our supergraph compose locally, and our changes are ready for the next stage. We could just publish our updated schemas to GraphOS (we made changes in both listings
and reviews
) , but let's take a pause and first validate that these changes won't break anything. We're responsible developers, after all!
In this lesson, we will:
- Learn about the types of schema checks
- Understand how schema checks fit into the overall process of updating a supergraph
- Run a schema check locally using the Rover CLI
- Inspect the results of a schema check in Studio
What are 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.
We'll talk about three types of schema checks: build checks, operation checks, and linter checks.
Build checks
Build checks validate that a subgraph's schema changes can still compose successfully with other subgraph schemas in the supergraph.
For example, if a new type is added to one subgraph, a build check determines whether that addition is compatible with the rest of the subgraphs in the supergraph. If it isn't, we need to investigate the error and fix it.
Operation checks
Operation checks validate that a schema's changes won't break any operations that existing clients send to the graph.
For example, let's say a web client regularly sends a GraphQL query to retrieve data for its homepage. If a schema change involves adding a required argument to a field in that query, it might break that client's existing operation if it doesn't include that argument! An operation check helps us guard against this potential failure, listing out the affected operations and allowing the team to address them.
Linter checks
Linter checks analyze your proposed schema changes for violations of formatting rules and other GraphQL best practices. GraphOS provides a set of default rules you can configure to suit your team's conventions. You can see a full list of rules in the Apollo documentation.
Some common schema conventions include: writing field names in camelCase
, type names in PascalCase
, and enums in SCREAMING_SNAKE_CASE
.
Running checks with Rover
We can run these checks right from the command line using Rover. Rover assesses our local changes for how they'll impact what we've already got in production. Its output will tell us everything we need to know—and what we need to fix!—before publishing our changes.
Running schema checks: rover subgraph check
To perform a schema check for a subgraph, we use the rover subgraph check
command with the following parameters:
rover subgraph check <APOLLO_GRAPH_REF> \--schema <SCHEMA_FILE_PATH> \--name <SUBGRAPH_NAME>
This command runs the schema checks then reports the results to Studio, so we can view them from our graph's Checks page.
Running checks on reviews
Let's start by checking our changes in the reviews
subgraph.
Open up a new terminal in the reviews
directory and paste in the rover subgraph check
command. Make sure you replace the parameters with your own values.
rover subgraph check <APOLLO_GRAPH_REF> \--schema ./src/schema.graphql \--name reviews
After the process completes, we can see a report of the schema changes. The terminal output shows the following:
Checking the proposed schema for subgraph reviews against Airlock@currenterror[E029]: Encountered 1 build error while trying to build subgraph "reviews"into supergraph "Airlock@current".Caused by:INVALID_FIELD_SHARING: Non-shareable field "Listing.id" is resolvedfrom multiple subgraphs: it is resolved from subgraphs "listings" and "reviews"and defined as non-shareable in subgraph "listings"The changes in the schema you proposed for subgraph reviews are incompatiblewith supergraph Airlock@current. See https://www.apollographql.com/docs/federation/errors/for more information on resolving build errors.
So, what's this INVALID_FIELD_SHARING
error? Well, the reviews
subgraph declares Listing
as an entity, but as far as our schema registry knows, the listings
subgraph does not! And it was the subgraph that originally defined the Listing
type, so this looks a bit problematic.
Let's take a closer look at this. We can check out the results of this schema check (and any past checks) in Studio as well. (Rover adds a link to this specific check at the end of its message.)
Head over to your supergraph in Studio and navigate to the Checks page. You'll see the same results reflected there.
When we click into the check, we can see more detail about any problems that it may have found.
It looks like we're dealing with an order-of-operations problem. The schema registry doesn't know about the changes that we've made to the listings
subgraph, so let's run the same check on our listings
subgraph.
Running checks on listings
In your terminal, navigate to the listings
directory, and run the following command. Be sure that you specify your own graph ref.
rover subgraph check <APOLLO_GRAPH_REF> \--schema ./src/schema.graphql \--name listings
When we run this command, we should see the following output.
There were no changes detected in the composed API schema, but the core schema was modified.
Recall that there was only one thing that we changed in our listings
schema: we turned the Listing
type into an entity. Let's jump back into Studio and review the new entry on the Checks page.
Click into this check and select Build from the TASK panel. Then, from under the WORKFLOW panel, click the button View schema.
This gives us two options: we can view the listings
subgraph schema that we ran a check against, or we can view the entire supergraph schema that would be composed with the latest changes. Let's click on just the listings
subgraph schema option for now.
This option shows us the full subgraph schema that we ran the check against. And we can see the @key
directive and primary key field that we specified for the Listing
entity here.
To take care of the error that appeared when we ran checks on the reviews
subgraph, we just need to follow a specific order when publishing our subgraphs: first, we'll publish the changes to our listings
subgraph that register Listing
as an entity type. Then we can follow up by publishing our reviews
subgraph changes, and our error will have vanished! Let's tackle this in our next and final lesson.
Practice
Drag items from this box to the blanks above
Field
Linter
Deprecated
Subgraph
Operation
Build
rover subgraph check
command need?Key takeaways
- Schema checks help identify potential failures caused by schema updates before they can cause issues in production.
- Build checks validate that a subgraph's schema changes can still compose successfully with other subgraph schemas.
- Operation checks validate that a schema's changes won't break any operations that existing clients are sending to the graph.
- Linter checks validate that a schema follows formatting rules and conventions.
- To run a schema check, we use the
rover subgraph check
command. - We can inspect the results of a schema check through the terminal or in the Studio Checks page.
Up next
Using GraphOS tools like Rover and Studio, we've validated that our schema changes are safe and don't break anything! 🎉 Next up, we'll publish our subgraph schemas.
Share your questions and comments about this lesson
This course is currently in
You'll need a GitHub account to post below. Don't have one? Post in our Odyssey forum instead.