Overview

We've seen our supergraph compose locally, and our changes are ready for the next stage. To bring our recommendedPlaylists feature into our graph, we need to tell GraphOS about how our schema has changed!

We could just publish our new soundtracks schema to GraphOS, 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 two types of schema checks (build checks and operation checks, linter)
• 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:

This command runs a build check first, then an operation check, and finally outputs the results in the command line. It also reports the results to Studio, so we can view them from your graph's Checks page.

Time to use our supergraph's graph ref again! We can find this value in Studio, at the top of the graph's README page, or grab it where we stored it in our router/.env file.

Next, let's open up a new terminal and paste in the rover subgraph check command. Make sure you replace the parameters with your own values.

After the process completes, we can see a report of the schema changes. The terminal output shows the following:

The first column indicates whether each change passed or failed the check. The second column indicates the type of change we made, such as FIELD_ADDED. The last column provides a more detailed description of the change, such as what exact type was created and what field was added under the type.

Awesome, we have no errors! The single change we made received a PASS status. We can also see that our change was compared against a number of existing client operations, and no breaking changes were detected.

We can check out the results of this schema check (and any past checks) in Studio too! 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.

Optional: A failed check

For fun, let's see what would have happened if one of our checks failed.

Open up the schema.graphqls file and find the Recipe.recommendedPlaylists field. Change the lowercase r to a capital R so it says RecommendedPlaylists.

In a terminal window, run the schema check again.

After the process completes, we can see a report of the schema changes. The terminal output shows the following:

We can see that our operation checks passed, and so did the linter checks, but with a warning: Field names should use camelCase style. We can view the check results in Studio as well.

Before we forget, let's revert that recommendedPlaylists change to get our checks passing again!

Practice

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! 🎉 It's time to publish our changes to our supergraph's graph registry.