9. Schema checks and launches
10m

Overview

We've seen our compose locally, and our changes are ready for the next stage. We could just publish our updated schemas to (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 two types of (build checks and checks, linter)
  • Understand how fit into the overall process of updating a
  • Run a schema check locally using the
  • 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 or breaking existing client . With , we can ensure that our schema changes won't cause issues when we deploy to production.

We'll talk about three types of : build checks, checks, and linter checks.

Build checks

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

For example, if a new type is added to one , 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

Operation checks

Operation checks validate that a schema's changes won't break any that existing clients send to the .

For example, let's say a web client regularly sends a to retrieve data for its homepage. If a schema change involves adding a required to a in that , it might break that client's existing 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.

Illustration of Studio checking a schema against existing operations

Linter checks

Linter checks analyze your proposed schema changes for violations of formatting rules and other best practices. 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 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 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 , 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 then reports the results to Studio, so we can view them from our 's Checks page.

Running checks on reviews

Let's start by checking our changes in the reviews .

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.

reviews
rover subgraph check <APOLLO_GRAPH_REF> \
--schema src/main/resources/schema/schema.graphqls \
--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@current
There were no changes detected in the composed API schema, but the core schema was modified.
Operation Check [PASSED]:
Compared 2 schema changes against 2 operations.
┌────────┬─────────────┬─────────────────────────────────────────────┐
│ Change │ Code │ Description │
├────────┼─────────────┼─────────────────────────────────────────────┤
│ PASS │ FIELD_ADDED │ type `Listing`: field `reviews` added │
├────────┼─────────────┼─────────────────────────────────────────────┤
│ PASS │ FIELD_ADDED │ type `Listing`: field `overallRating` added │
└────────┴─────────────┴─────────────────────────────────────────────┘
View operation check details at: https://studio.apollographql.com/graph/[LINK_TO_YOUR_CHECK]
Linter Check [PASSED]:
Resulted in 1 warning.
┌─────────┬────────────┬──────┬─────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┐
│ Level │ Coordinate │ Line │ Description │
├─────────┼────────────┼──────┼─────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┤
│ WARNING │ Listing │ 11 │ Type "Listing" is declared as an entity (has a @key applied) in some but not all defining subgraphs: it has no @key in subgraph "listings" but has some @key in subgraph "reviews". │
└─────────┴────────────┴──────┴─────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┘
View linter check details at: https://studio.apollographql.com/graph/[LINK_TO_YOUR_CHECK]

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 was added under the type.

We can see that our check passed: both new have a PASS status.

However, our linter check passed with a warning: the reviews declares Listing as an , but as far as our schema registry knows, the listings does not!

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. ( 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.

studio.apollographql.com

The Checks page in Studio, showing a successful new entry

When we click into the check, we can see more detail about any problems that it may have found, including warnings from the linter.

studio.apollographql.com

Further detail about the recently run check, showing that build was successful

Note: By default, all linter rules are set to "Warn". To view and change the severity of a rule, click "View Configuration". The full list of rules and their severity can be changed on that page.

This warning from the linter won't stop us from publishing our , but before we do, let's run the same check on our listings .

Running checks on listings

In your terminal, navigate to the listings directory, and run the following command. Be sure that you specify your own .

listings
rover subgraph check <APOLLO_GRAPH_REF> \
--schema src/main/resources/schema/schema.graphqls \
--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 . Let's jump back into Studio and review the new entry on the Checks page.

studio.apollographql.com

The check entry that was run for the listings subgraphl

Click into this check and select Build from the TASK panel. Then, from under the WORKFLOW panel, click the button View schema.

studio.apollographql.com

Clicking into the check, and selecting the Build resultsl

This gives us two options: we can view the listings that we ran a check against, or we can view the entire that would be composed with the latest changes. Let's click on just the listings option for now.

studio.apollographql.com

Clicking into the check, and selecting the Build resultsl

This option shows us the full that we ran the check against. And we can see the @key and primary key that we specified for the Listing here.

studio.apollographql.com

Clicking into the check, and selecting the Build resultsl

To take care of the warning that appeared when we ran checks on the reviews , we just need to work out our order of when publishing: first, we'll publish the changes to our listings that register Listing as an type. Then we can follow up by publishing our reviews changes, and our warning will have vanished! Let's tackle this in our next and final lesson.

Practice

Types of schema checks
Schema checks identify potential failures from proposed schema changes. 
 
 checks validate that a schema follows GraphQL conventions. 
 
 checks validate that existing client operations won't break. 
 
 checks validate that the supergraph schema will still compose successfully.

Drag items from this box to the blanks above

  • Deprecated

  • Field

  • Subgraph

  • Build

  • Operation

  • Linter

Which of the following information does the rover subgraph check command need?

Key takeaways

  • help identify potential failures caused by schema updates before they can cause issues in production.
  • Build checks validate that a 's schema changes can still compose successfully with other .
  • checks validate that a schema's changes won't break any operations that existing clients are sending to the .
  • 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.

Previous

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.