docs: add docs page for schema registry

PR-URL: https://github.com/hasura/graphql-engine-mono/pull/9606
Co-authored-by: github-actions[bot] <41898282+github-actions[bot]@users.noreply.github.com>
Co-authored-by: Rikin Kachhia <54616969+rikinsk@users.noreply.github.com>
GitOrigin-RevId: d0dedd3dd85fec697c342c864afc381be9a9334f
This commit is contained in:
Rishichandra Wawhal 2023-06-21 11:34:26 +05:30 committed by hasura-bot
parent 03731621d5
commit 54f9eca1a3
6 changed files with 87 additions and 0 deletions

View File

@ -0,0 +1,87 @@
---
sidebar_position: 4
sidebar_label: Schema Registry
description: Registry for GraphQL schemas of your Hasura project
title: 'GraphQL Schema Registry'
keywords:
- hasura
- docs
- cloud
- schema
- schema-registry
---
import Thumbnail from '@site/src/components/Thumbnail';
import ProductBadge from '@site/src/components/ProductBadge';
# Schema Registry
<ProductBadge standard free standard pro/>
>
:::info Note
Schema Registry is available on Hasura Cloud on and after version v2.26.0-cloud.1
:::
## Overview
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 your schema and make collaboration across large teams, micro services and roles much more manageable and predictable. You can find Schema Registry in the settings page of your Hasura Console.
<Thumbnail src="/img/observability/schema-registry/schema-registry-listing.png" alt="Hasura Cloud Schema Registry Listing" />
## How it works
Whenever there is any operation on Hasura that could change the GraphQL schema, Hasura sends an event to the schema registry with the GraphQL schemas for all the Hasura roles. The operations that could change the GraphQL schema include:
- Applying new metadata
- Reloading metadata
- Hasura version update
Schema registry stores GraphQL schemas for all the roles present in the Hasura metadata. It also shows all the changes that went into each role based schema with respect to the schema for the same role in the previous schema registry entry. For example, the schema registry entry in the screenshot below has schemas for 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 that there are potentially 5 breaking changes, 4 dangerous changes and 1 safe change.
<Thumbnail src="/img/observability/schema-registry/schema-registry-inter-role-changes.png" alt="Hasura Cloud Schema Registry Role Based Changes" />
If you expand a schema, you can see that GraphQL schema in GraphQL SDL syntax in the `GraphQL` tab. If you click on the `Changes` tab, you can see all the changes in the current GraphQL schema with respect to the previous schema for that role.
<Thumbnail src="/img/observability/schema-registry/schema-registry-schema-details-changes.png" alt="Hasura Cloud Schema Registry Schema Changes" />
:::info Note
If there was no previous schema to compare against, the GraphQL schema changes are considered to be zero.
:::
## Kind of schema changes
The changes between subsequent schemas are computed using the open source [GraphQL Inspector](https://github.com/kamilkisiela/graphql-inspector).
### Breaking changes
Breaking changes are typically the schema 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 usecases of schema registry, it can primarily be used for reliable development, auditing your your production GraphQL schema and making it more predictable.
When new changes are deployed to a staging or pre-production environment, before moving to production, you can verify whether all the breaking and dangerous have been accounted for in the queries made by the 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.
Schema registry can also be used to audit the past GraphQL schemas of your project and observe when certain schema changes took place and how.
## Alerts
The Schema Registry sends an email to the owner of the project whenever there are any changes in the GraphQL schema of the project. You can configure your mailing preferences by clicking the bell icon in the Schema Registry page.
<Thumbnail src="/img/observability/schema-registry/schema-registry-alert-config.png" alt="Hasura Cloud Schema Registry Alert Config" />

Binary file not shown.

After

Width:  |  Height:  |  Size: 34 KiB

Binary file not shown.

After

Width:  |  Height:  |  Size: 197 KiB

Binary file not shown.

After

Width:  |  Height:  |  Size: 49 KiB

Binary file not shown.

After

Width:  |  Height:  |  Size: 138 KiB

Binary file not shown.

After

Width:  |  Height:  |  Size: 171 KiB