Schema Registry
Introduction
The Schema Registry, as the name suggests, is a registry which stores all the GraphQL schemas that have existed on your Hasura project. It is aimed at making your Hasura GraphQL schema changes more reliable, prevent breaking changes in the schema and to make collaboration across large teams, microservices and roles more manageable and predictable. You can find the Schema Registry in the settings page of your Hasura Console.
Schema Registry is available on Hasura Cloud from v2.26.0-cloud.1 and above.
How it works
Whenever there is any operation on the Hasura Engine that could change the GraphQL schema, Hasura sends an event to the
Schema Registry along with the GraphQL schemas for all defined roles. Operations which could change the GraphQL schema include:
- Applying new metadata
- Reloading metadata
- Hasura version update
The registry also shows all the changes that went into each role's schema relative to the previous schema registry entry for that role.
For example, the Schema Registry entry in the screenshot below has schemas for the roles admin and user. It shows 5
breaking changes, 4 dangerous changes and 1 safe change in the user schema. This means that the user schema has
changed in a way which now presents the aforementioned warnings.
If you click to expand a schema, you can see the schema in GraphQL SDL syntax in the GraphQL tab. If you click on the
Changes tab, you can see all the changes relative to the previous schema for that role.
If there was no previous schema to compare against, there will be no changes to present.
Kind of schema changes
The changes between subsequent schemas are computed using the open source GraphQL Inspector.
Breaking changes
Breaking changes are typically the changes that could potentially break your GraphQL operations (queries, mutations or subscriptions) at the GraphQL operation validation layer.
For example, if a field name is removed from a GraphQL object type user, that counts as a breaking change as it
could potentially fail an existing GraphQL operation that queries the name field in the user type.
Dangerous changes
Sometimes there are changes in your GraphQL schema that might not necessarily break your GraphQL operations at the validation layer, but might sometimes affect their behaviours.
For example, if a new nullable field is added to an input type, that wouldn't break your GraphQL query but might affect its execution. These changes are categorised as dangerous changes.
Safe changes
The GraphQL schema changes that can not affect your existing GraphQL operations are considered to be safe. These changes typically include new type definitions and new fields in object types.
Usage
While there can be many use cases for the Schema Registry, it can primarily be used for reliable development, auditing, and ensuring predictability of your GraphQL schema changes.
As new changes are deployed to a staging or pre-production environment, but before moving to production, you are able to verify whether all the breaking and dangerous have been accounted for in queries made by clients of your GraphQL API.
Also, if you're using Hasura Cloud for development, you can see the schema changes with every change to your GraphQL schema and update the corresponding GraphQL queries accordingly.
The Schema Registry can also be used to audit the past schemas of your project and observe when and how certain schema changes took place.
Alerts
The Schema Registry provides the following options to configure notifications by clicking the bell icon in the Schema Registry page:
Email
The Schema Registry sends an email to the owner of the project whenever there are any changes in the GraphQL schema of the project.
Slack
The Schema Registry sends an aggregate summary of GraphQL schema changes to the configured Slack channel of the respective workspace. Follow these steps to configure Slack alerts:
Click the "Add to Slack" button in the Slack tab.
Select the Slack channel in your workspace in which you want alerts to appear. Click Allow to authorize.
Slack alerts should be configured for the selected channel in your workspace. You can choose to disable the alerts by clicking on the delete icon.
