Join us for GraphQL Summit, October 10-12 in San Diego. Use promo code ODYSSEY for $400 off your pass.
Launch GraphOS Studio

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 s still compose to a valid schema. 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 changes and attempts to compose a schema from all of your registered s.

  • If composition succeeds, the result is compared against your most recently registered 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 .

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 querying.
  • Failed composition is a failure due to inability to compose the graph, like missing a required @key for an entity.

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 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 . When this occurs, your subgraph's registered 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 "" 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 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 to function as it was before the most recent deployment. Additionally, this functionality can be used to make dependent changes, like smoothly migrating a from one to another or introducing a circular dependency.

Deployment best practices
Edit on GitHubEditForumsDiscord