Join us from October 8-10 in New York City to learn the latest tips, trends, and news about GraphQL Federation and API platform engineering.Join us for GraphQL Summit 2024 in NYC
Docs
Start for Free

Federated Schema Checks

Use schema checks for independent and safe subgraph development


💡 TIP

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 , takes your schema changes and attempts to compose a supergraph schema from all of your registered subgraph schemas.

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

ⓘ NOTE

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

  • 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 required @key for an .

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 '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 "Author.name" can only be defined once.
There can be only one type named "Author".
Field "Book.title" can only be defined once.
Field "Book.author" 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 router 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.

Previous
Uplink
Next
Deployment Best Practices
Rate articleRateEdit on GitHubEditForumsDiscord

© 2024 Apollo Graph Inc., d/b/a Apollo GraphQL.

Privacy Policy

Company