Here's your chance to speak at GraphQL Summit in New York City, October 8 - 10, 2024! 🏙️ Submit your proposal by May 31.
Launch GraphOS Studio
You're viewing documentation for a previous version of this software. Switch to the latest stable version.

Federated schema checks

For an introduction to , see Schema checks.

Whenever you make changes to a , running rover subgraph check helps ensure that all your still compose to a valid . This helps teams work independently on their portion of your federated graph without negatively affecting your users or other teams.

When you run rover subgraph check on a particular , Apollo Studio takes your schema changes and attempts to compose a supergraph schema from all of your registered subgraph schemas.

  • If composition succeeds, the result is compared against your most recently registered supergraph schema to confirm that no known clients are affected by the proposed changes.
  • If composition fails, validation ends and results are returned to the user.

Running rover subgraph check never updates your current registered supergraph schema.

Handling check failures

There are two types of failures that can occur during validation: failed usage checks and failed .

  • Failed usage checks are failures due to breaking changes, like removing a that an active client is .
  • Failed composition is a failure due to inability to compose the , like missing a @key for an extended .

In most cases, you should run rover subgraph publish only after a successful run of rover subgraph check. However, certain workflows require intentionally publishing a subgraph schema that fails composition (such as migrating an entity or field between subgraphs).

Even after rover subgraph check succeeds, however, it's possible that rover subgraph publish encounters composition errors because of simultaneous changes to another subgraph. When this occurs, your subgraph's registered schema is still updated as long as it is spec-compliant. However, the supergraph schema is not updated. This means that your gateway's configuration is also not updated.

An example output of this behavior looks like this:

$ rover subgraph publish docs-example-graph@current --name books --schema ./schema.graphql
Publishing SDL to docs-example-graph:current (subgraph: books) using credentials from the default profile.
The gateway for the 'docs-example-graph' graph was NOT updated with a new schema
WARN: The following composition errors occurred:
Field "" can only be defined once.
There can be only one type named "Author".
Field "Book.title" can only be defined once.
Field "" can only be defined once.
There can be only one type named "Book".

The reasoning behind this functionality is that the Apollo schema registry should always reflect what is running in your infrastructure. Even if that means that composition is failing in your infrastructure, the registry should reflect that.

However, you still want your gateway to function as it was before the most recent deployment. Additionally, this functionality can be used to make dependent changes, like smoothly migrating a field from one subgraph to another or introducing a circular dependency.

Deployment best practices
Edit on GitHubEditForumsDiscord

© 2024 Apollo Graph Inc.

Privacy Policy