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 variant. Fortunately, there's an Apollo Studio feature to help with that: schema checks!

In this lesson, we will:

  • Learn about the two different types of schema checks (composition checks and operation checks)
  • Understand how schema checks fit into the overall process of updating a supergraph
  • Learn about the launch process in Apollo Studio

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

There are two types of schema checks: composition checks and operation checks.

Composition checks

Composition checks validate that a subgraph's schema changes can still compose successfully with other subgraph schemas in the supergraph.

Composition checks are only available for federated graphs, because non-federated graphs aren't composed into a supergraph.

Illustration of subgraph characters being checked for composition

For example, if a new type is added to one subgraph, a composition 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. We'll take a look at common composition errors later on in the course.

Operation checks

Operation checks validate that a schema's changes won't break any operations that existing clients send to the graph. Unlike composition checks, operation checks are available for non-federated graphs in addition to federated graphs.

Illustration of Studio checking a schema against existing operations

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! An operation check helps us guard against this potential failure, listing out the affected operations and allowing the team to address them. We'll also take a look at an example of this later on in the course.

How to run schema checks

There are two main ways to run schema checks. We can run schema checks locally, using the Rover CLI. We can also integrate schema checks into our CI pipelines to run automatically (which lets us do things like block merging any pull request that fails schema checks). We'll get to the pipeline stuff later in the course. For now, we'll focus on running schema checks locally.

To perform a schema check for a subgraph, we use the Rover CLI's rover subgraph check command. This runs a composition check first, then an operation check, and finally outputs the results in the command line. It also reports the results to Apollo Studio, so you can view them from your graph's Checks page. We'll see schema checks in action in the next lesson.

Schema checks in the supergraph story

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

After making changes to a subgraph schema (whether that's adding, removing, or updating definitions), we first want to run schema checks locally using Rover. For a supergraph, a composition check happens first, then operation checks run.

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

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

Illustration using Rover for a local composition check, variants in the registry

If either check fails, Rover 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 Rover to publish the subgraph schema 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 Apollo Studio: a launch.

Launch process

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

A launch represents the complete process of making schema updates to any variant of a graph. You'll already be familiar with some of the steps in a launch (we covered them in Voyage I), but there are a few new steps thrown in the mix to include our handy schema checks!

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

At the same time, Studio also runs an operation check. This is the same one we ran locally earlier, but Studio runs it again to double check any changes. If any errors come up in the operation check, the launch still completes but with warnings. We can investigate these errors in the Launches page of Studio. We'll dive deeper into how to deal with these errors later on in the course.

If the operation check completes successfully, the launch is also completed. We've successfully completed our schema updates to the graph!

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 schema checks and the launch process look like in our supergraph.

Practice

Schema checks

There are two types of schema checks. Checks that validate if a subgraph's schema changes can still
 
successfully with other subgraph schemas are called
 
, which are available for
 
. Checks that validate a schema's changes against existing
 
sent by clients are called
 
, which are available for
 
.

Drag items from the box to the blanks above

supergraph checks
query checks
combine
federated graphs
operations
combination checks
compose
both federated and non-federated graphs
non-federated graphs
operation checks
composition checks

Which of the following statements about launches in Apollo Studio are true?

Key takeaways

  • Schema checks help identify potential failures caused by schema updates before they can cause issues in production. There are two types of schema checks: composition checks and operation checks.
  • Composition checks validate that a subgraph's schema changes can still compose successfully with other subgraph schemas. These checks are only available for federated graphs.
  • Operation checks validate that a schema's changes won't break any operations that existing clients are sending to the graph. These checks are available for both federated and non-federated graphs.
  • To run a schema check, we use the rover subgraph check command.
  • A launch represents the complete process of making schema updates to any variant of a graph. It's triggered by a subgraph being published to the schema registry.

Up next

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

Previous
Next