Skip to main content
Version: v2.x

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.

Hasura Cloud Schema Registry Listing
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

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.

Hasura Cloud Schema Registry Role Based Changes

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.

Hasura Cloud Schema Registry Schema Changes
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.

Hasura Cloud Schema Registry Alert Config

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.

    Hasura Cloud Schema Registry Add To Slack
  2. Select the Slack channel in your workspace in which you want alerts to appear. Click Allow to authorize.

    Hasura Cloud Schema Registry Select Slack Channel
  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.

    Hasura Cloud Schema Registry Configured Slack Alerts