Breeze through collaboration with the Hasura Schema Registry

“Pagerduty alert: Rise in user tickets after a release”                                “Urgent war room on a user facing breaking change!”

Not just as an SRE, but as an Engineering Manager and as a software engineer in one of the several many teams that contributed to the latest release, haven’t we all been in this situation where, something broke suddenly even after rigorous testing and you’re woken up in the middle of the night to escalate and fix it? With Hasura Schema Registry this is exactly what we’re trying to address!

As the software product that we’re building becomes more and more complex, and as the number of teams working on the code together becomes larger and larger, there’s only so much you can do to exhaustively test every single change that is to go into the latest release.

As a developer on Team A, I want to make sure that none of my changes are breaking those of Team B. But the constraint is I won’t know before all the changes are merged into main, and with the size of code there is, at that level it only becomes more difficult to test.

And as a platform manager, I want to ensure my top level is coherent and doesn’t break my consumer applications. Sure, for code we have the GitHubs and GitLabs of the world. But we wish we had a version control system in the API world, too, right?

The Hasura Schema Registry is a version control system for your Hasura GraphQL schema. This shows you the difference between two subsequent versions of your GraphQL schema so you can audit and release API changes to production with confidence. You can also configure alerts on your pre-production environments to catch breaking changes in time.

The Schema Registry is available to all Hasura Cloud users starting v2.26. Just head to Settings -> Schema Registry (Beta) on your Cloud project’s console. The Schema Registry shows you changes to your schema classified by  ‘Breaking’,, ‘Dangerous,’ and ‘Safe’ since the last snapshot. You can look into each change by clicking into each time- snapped entry.

Let’s look at an example. I have connected a new database to my Hasura instance and tracked an ‘order’ table into my schema. The Schema Registry entry then shows all the changes that newly modified my GraphQL schema; that is, fields and queries, mutations and subscription types associated with the ‘order’ table.

As these are new changes that weren't affecting the previous schema, all of these are classified as ‘Safe’ changes.

As a next step, if I remove a table called ‘region’ from my GraphQL schema, that shows up as ‘Breaking’ changes in my Schema Registry entry, which means if I had consumer applications that were querying this ‘region’ table, they would break!

The Schema Registry service automatically computes differences between each subsequent schema instantaneously and will be available on the Schema Registry tab for all your Hasura Cloud projects.

This means that you do not need to do any additional setup  on your end – and can immediately start looking at the schema changes of your desired project and get productive.

The Hasura Schema Registry also becomes super important for auditing your role-based schemas.

In the registry, you’ll be able to see one entry for each role you have set up on your GraphQL schema. In my example, I have two roles - admin and user. The ‘User’ role has limited permissions to access and insert to fields in certain tables. So if I have changes in my GraphQL schema that impacts only the ‘user’ role, those can be seen in the role-based entry in my registry.

Not getting a good night’s sleep worried something might break? Schema Registry Alerts to the rescue!

The Schema Registry becomes an extremely powerful capability when used in conjunction with your staging or pre-production environments.

As someone monitoring your top-level API, you now have the capability to get proactively alerted when worrisome schema changes occur in your staging and pre-production environments.  This will enable  you to verify them before going live  so that breaking changes are not inadvertently introduced to your downstream consumer facing applications..

Say I had a user-facing application that was querying my Hasura API for the ‘region’ information, and accidentally one of my teams deleted the ‘region’ table. In the Schema Registry of my pre-prod instance, I get alerts on breaking changes in my top-level schema. The registry entry can then be quickly reviewed to look for changes and appropriate fixes can be done as needed before pushing the latest changes to production!

You can customize alerts also so that you can be alerted only for the changes that concern you.

This also  enables easier and smoother collaboration between multiple teams, and you can make sure that changes to your unified API are coherent and reliable.

In this blog post, we discussed how Hasura’s Schema Registry can audit and proactively alert you on changes to your GraphQL schema and enable you to release API changes to production with confidence.

To get started now, sign-up for Hasura Cloud, check out our docs here and reach out to us for any questions or feedback.