Schema Checks

The Schema Registry can a run a suite of checks on a schema.

In a federated graph, you can check a subgraph schema before publishing.

CLI

Schema Checks are run with the grafbase check command. It takes the following arguments:

  • a required graph reference positional argument
  • --name: the name of the subgraph. It is required in federated graph projects, and invalid in standalone graph projects.
  • --schema: the path to the GraphQL schema file. If this argument is not provided, the CLI will attempt to read the schema from stdin.

On successful check, the command returns with a successful exit code (0).

If there are any check errors, the command returns with a non-zero exit code and prints the errors. This makes the command suitable for use in scripts and CI pipelines.

Examples

Introspect the schema of a local graph and check it:

$ grafbase introspect --dev | grafbase check myaccount/mygraph@main --name mysubgraph

Dashboard

To see past schema checks, you can visit the Checks tab in the Grafbase dashboard.

Schema Checks tab in the dashboardd

If you use GitHub Actions for CI, there is a pre-packaged and documented grafbase-schema-check action that uses the same approach as the description below..

The command can be used in scripts. You only need to provide the same arguments as you would interactively.

The main difference will be authentication. Instead of following the interactive login flow with grafbase login, you must provide a Grafbase access token. You can generate an access token from the dashboard:

Access tokens view in the dashboard

In Grafbase projects, grafbase introspect --dev command is the most convenient way to generate the GraphQL schema file to pass to the --schema argument of grafbase check. You can see an example in the GitHub workflow of the example repository for checks in CI. There is also a federated graph example.

Schema checks in more detail

When you initiate a schema check with grafbase check, the Schema Registry:

  1. Gathers all subgraph schemas for the branch
  2. Validates that each schema is a valid GraphQL schema on its own
  3. Tries to compose all the subgraph schemas together, with the new version of the named subgraph that was passed to check

If any error happens in step 2. or 3., the Schema Check fails.