4. Schema checks
3m

Overview

We could just merge our changes and let know about them, 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)
  • 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 updates. They check for issues like incompatibilities between subgraph s or breaking existing client s. With , we can ensure that our changes won't cause issues when we deploy to production.

We'll talk about two types of : build checks and checks.

Build checks

Build checks validate that a subgraph's changes can still compose successfully with other subgraph s in the .

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 . If it isn't, we need to investigate the error and fix it.

Illustration of subgraph characters being checked for composition

Note: Our Poetic Plates only has one subgraph (recipes) right now, so build checks aren't too relevant for us at this stage!

Operation checks

Operation checks validate that a 's changes won't break any s 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 change involves adding a required to a in that query, it might break that client's existing if it doesn't include that ! An check helps us guard against this potential failure, listing out the affected s and allowing the team to address them.

Illustration of Studio checking a schema against existing operations

rover subgraph check

There are two main ways to run using the Rover CLI. We can run locally in our terminal (which we'll do shortly). We can also integrate into our CI pipelines to run automatically against new pull requests (we'll do this in the next lesson).

To perform a check for a subgraph, we use the rover subgraph check command with the following parameters:

rover subgraph check <GRAPH_REF> \
--schema <SCHEMA_FILE_PATH> \
--name <SUBGRAPH_NAME>

Note: The graph reference (or graph ref) tells Rover about our . A graph ref starts with the graph's ID, followed by an @ symbol, followed by the graph variant.

This command runs a build check first, then an 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.

Running schema checks

Let's give it a try! We made changes by deprecating a and adding a new in the previous lesson, so let's make sure those changes are safe before pushing them up to our .

First let's grab the graph reference for our . We can find this value in Studio, at the top of the graph's README page.

https://studio.apollographql.com

Studio README page pointing to the graph reference

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.

rover subgraph check poetic-plates-supergraph@main \
--schema schema.graphql \
--name recipes

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

Checking the proposed schema for subgraph recipes against poetic-plates-supergraph@main
Check Result:
Compared 2 schema changes against 123 operations
┌────────┬──────────────────┬──────────────────────────────────────────────────────┐
│ Change │ Code │ Description │
├────────┼──────────────────┼──────────────────────────────────────────────────────┤
│ PASS │ FIELD_DEPRECATED │ type `Ingredient`: field `text` deprecated │
├────────┼──────────────────┼──────────────────────────────────────────────────────┤
│ PASS │ FIELD_ADDED │ type `Ingredient`: field `detailedDescription` added │
└────────┴──────────────────┴──────────────────────────────────────────────────────┘
View full details at [Studio URL]

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 and FIELD_DEPRECATED. The last column provides a more detailed description of the change, such as what exact type was created and what was added under the type.

Awesome, we have no errors! We can tell that the checks passed, because each row in the output table has a PASS status. The changes were also compared against the number of existing client s, and no breaking changes were detected.

We can check out the results of this 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 in Studio and navigate to the Checks page. You'll see the same results reflected there.

https://studio.apollographql.com

The Studio Checks page showing the results of the latest schema check

Practice

Which of the following information does the 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.
  • 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 schema registry.

Previous
Next

Share your questions and comments about this lesson

This course is currently in

beta
. Your feedback helps us improve! If you're stuck or confused, let us know and we'll help you out. All comments are public and must follow the Apollo Code of Conduct. Note that comments that have been resolved or addressed may be removed.

You'll need a GitHub account to post below. Don't have one? Post in our Odyssey forum instead.