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. From the
API tab, you can find the Schema Registry option at the top of the screen.
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
Within the Schema Registry tab, you'll find an organized interface to explore schema changes. The layout consists of a list of schema changes on the left side and an information card on the right, providing in-depth details about each change.
By default, the Schema Registry showcases the alterations associated with the 'admin' role in the context of the latest schema change. This default view simplifies the process of staying informed about the most recent schema adjustments for this specific role.
For instance, below, you can see the changes displayed for the highlighted card, which contains details for both the
The right section provides insights into how this specific schema change impacted the
admin role, which is currently
selected. It reveals that there are the following changes concerning the
These numbers indicate that the schema has been modified in a manner that triggers the warnings and alerts mentioned.
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 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
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.
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.
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.
The Schema Registry provides the following options to configure notifications by clicking the bell icon in the Schema Registry page:
The Schema Registry sends an email to the owner of the project whenever there are any changes in the GraphQL schema of the project.
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.