Schema Registry

Available on: Cloud Free, Cloud Professional

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. From the API tab, you can find the Schema Registry option at the top of the screen.

Note

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 admin and user roles.

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 admin role:

• 0 breaking changes
• 7 dangerous changes
• 4 safe changes

These numbers indicate that the schema has been modified in a manner that triggers the warnings and alerts mentioned.

Note

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:

1. Click the "Add to Slack" button in the Slack tab.

   

2. Select the Slack channel in your workspace in which you want alerts to appear. Click Allow to authorize.

   

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