4. Schema checks in a supergraph
7m

Overview

The Listings team has some exciting updates ready to publish to the registry, but they need to be confident in these schema changes before publishing them to the production . Fortunately, there's an feature to help with that: !

In this lesson, we will:

  • Learn about the different types of
  • Understand how fit into the overall process of updating a
  • Learn about the process in

In this lesson, we'll focus mainly on the high-level overview of the process. The next lesson will dive more into the details of how to run each check.

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.

There are 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 .

Illustration of subgraph characters being checked for composition

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.

Operation checks

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

Illustration of Studio checking a schema against existing operations

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.

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.

How to run schema checks

There are two main ways to run using the . We can run schema checks locally in our terminal. We can also integrate schema checks into our CI pipelines to run automatically against new pull requests.

To perform a schema check for a , 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 ) tells about our . A graph ref starts with the graph's ID, followed by an @ symbol, followed by the .

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

Schema checks in the supergraph story

Let's revisit our story and zoom in to where occur and what happens when they fail, pass, or are actively overridden.

After making changes to a (whether that's adding, removing, or updating definitions), we first want to run locally using .

First, validates that a 's schema changes can still compose successfully with the other in the . By default, this check runs against the current of the , but we can also select any graph variant already registered in Studio.

If the build check succeeds, runs an check immediately after. This validates that the schema's changes won't break any operations that existing clients send to the .

If either check fails, provides a link to the Studio Checks page that contains more information about what went wrong.

If all the checks are successful, we can go ahead and follow the same process as before: we'll use to publish the to the registry.

Illustration of schema checks fitting into the story of a supergraph. See description in paragraphs above for full outline of the process.

While we're on the subject of publishing schema changes, let's take a moment to touch on a useful feature of : a launch.

Launch process

By publishing to the schema registry, we've triggered a launch in .

A represents the complete process of making schema updates to any of a .

A starts with attempting to compose the . If it fails, we'll see an error and the process stops there. Otherwise, a is produced. The supergraph schema is provided to Uplink and the will fetch the latest schema.

We've successfully completed our schema updates to the !

Illustration of launches and how they fit into the story of a supergraph. See description in paragraphs above for full outline of the process.

And that's what and the process look like in our .

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

  • Operation

  • Deprecated

  • Build

  • Linter

  • Subgraph

  • Field

Which of the following statements about launches in GraphOS are true?

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.
  • A represents the complete process of making schema updates to any of a . It's triggered by a being published to the schema registry.

Up next

In the next three lessons, we'll see how work in our development workflow and how they can be automated in the CI/CD process.

Previous

Share your questions and comments about this lesson

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.