Overview

It's time to introduce an integral part of GraphOS: the schema registry!

In this lesson, we will:

• Learn about the GraphOS schema registry and its uses
• Learn about the GraphOS launch process
• Publish a schema to the schema registry using the Rover CLI
• Inspect the results of a launch in Studio

What's the schema registry?

At its core, the schema registry is a version control system for our schema. It stores our schema's change history, tracking the types and fields that were added, modified, and removed. The registry powers almost every feature in Apollo GraphOS.

Similar to how we commit and push changes to our codebase to a Git repository, we should push every new version of our subgraph schema to the registry. The registry takes care of tracking all the subgraphs and composing them into one supergraph schema. It's also thanks to the registry that we can run schema checks, as we did in the previous lesson. GraphOS checks our schema changes against the schema stored in the registry.

In this course, we're starting small with just one subgraph in our supergraph. As we start adding more subgraphs, we'll continue to make use of the power of the schema registry!

When we publish a new version of a subgraph schema to the registry, we trigger a launch in GraphOS.

The launch process

A launch represents the complete process of making schema updates to a graph.

When the schema registry gets a new or updated version of a subgraph schema, it starts to build the supergraph schema. The schema registry attempts to combine all of the schemas from its registered subgraphs into a single supergraph schema. This process is also known as composition.

If composition fails, we'll see an error in Studio, and the process stops there. No stress: we can use the error messages to fix the issue in our subgraph, and then try publishing the subgraph with Rover again.

If composition succeeds and there are no validation errors, the schema registry produces a supergraph schema.

The schema registry automatically sends the supergraph schema to an internal service within GraphOS called Apollo Uplink. Uplink is a server that stores the latest supergraph schema for each graph. The router fetches the latest schema from Uplink and uses this new schema to respond to client requests.

With that, the launch completes successfully!

Coordinating schema and code changes

So far, we've only been talking about schema changes and how they should be published to GraphOS. But we can't forget about our codebase changes! These include the changes we made to the resolver functions to make our schema work and the schema file itself. We need to deploy our local changes to production.

To coordinate both schema and code changes, here's the plan:

1. Merge our codebase changes (the changes we made to schema.graphql and resolvers.js) to the main branch of our GitHub repository.

2. Deploy the runtime code for the subgraph server to Railway (this happens automatically, Railway is listening for changes to our GitHub main branch).

3. Publish the subgraph schema to GraphOS (which triggers the launch process).

Ideally, this is all taken care of by our CI/CD pipelines. First, we'll walk through what this process looks like manually, to get familiar with the commands we'll need and where to find the results. In the next lesson, we'll set up a CI/CD pipeline using GitHub Actions to take care of it automatically.

Merging codebase changes

All right, let's get to it! First, let's merge our codebase changes.

Let's commit the changes we made earlier and push them directly to the main branch. (We're in tutorial land, so we're okay with doing this! In the next lesson, you'll see a process that reflects a real-world scenario more closely using CI/CD workflows).

1. Open up a new terminal.

2. Add the files we've changed.

   git add schema.graphql src/resolvers

   Copy

3. Commit the changes with a clear message explaining what we've done.

   git commit -m "Deprecate Ingredient.text field. Use detailedDescription instead."

   Copy

4. Push the changes to the GitHub repo.

   git push -u origin main

   Copy

That's the first step done!

1. ✅ Merge our codebase changes to the main branch of our GitHub repository.

2. ⏭️ Deploy the runtime code for the subgraph server to Railway.

3. Publish the subgraph schema to GraphOS.

Step 2 doesn't need much work from us! Once our changes have landed in the main branch, Railway will automatically start its deployment process.

Head over to your Railway app and watch the loading bar until it says it has been successfully deployed with no issues! If you navigate to your server URL, there won't be any visible changes, but we know that behind the scenes, this subgraph is ready with a new field and a deprecated field!

1. ✅ Merge our codebase changes to the main branch of our GitHub repository.

2. ✅ Deploy the runtime code for the subgraph server to Railway.

3. ⏭️ Publish the subgraph schema to GraphOS.

Let's tackle the last step!

rover subgraph publish

We need to publish our new subgraph schema to GraphOS.

To do this, we'll use the Rover CLI's rover subgraph publish command with the following parameters:

It looks pretty similar to the rover subgraph check command!

Publishing our subgraph changes

Let's do it! In a terminal window, paste in the rover subgraph publish command. Make sure you replace the parameters with your own values.

If all goes well, we should see the terminal output with a message confirming that the subgraph has been published and the supergraph has been updated!

Inspecting a launch in Studio

What happens after a schema is published to the registry? A launch starts! Let's take a peek at that process in Studio.

Navigate to the Launches page. Click on the latest launch in the list.

We can see that the Launch Sequence section for this specific launch follows the steps we had talked about earlier:

• Build Completed refers to the process of building a supergraph schema (also known as composition).
• Schema Published refers to the supergraph schema made available to Apollo Uplink.
• Launch Completed is self-explanatory! Our launch successfully completed! 🎉

On the right-hand side, we can also take a look at the supergraph schema output and a summary of our schema changes.

If everything looks good to go, we should be able to query for the new detailedDescription field for an ingredient.

Let's go to Explorer and run a query to retrieve a random recipe's ingredients and a detailed description of each.

You should be seeing data come back! Let's try another one, adding text in the query this time.

The query still runs and comes back successfully, but we get a warning in the Explorer (that yellow squiggly line!) that text has been deprecated and not to use it anymore.

Our launch was successful! 🎉

Practice

Key takeaways

• The schema registry is a version control system for our schema. It stores our schema's change history, tracking the types and fields that were added, modified, and removed. The registry takes care of tracking all the subgraphs and composing them into one supergraph schema.
• A launch represents the complete process of making schema updates to a graph. A launch is triggered when a schema is published to GraphOS.
• To publish a subgraph schema, use the rover subgraph publish command.
• We can inspect the results of a launch through the Studio Launches page.

Up next

Awesome job! We've made changes to our supergraph safely and confidently with the help of GraphOS. We did all this manually, running schema checks and publish commands from the terminal, but this work should really live in an automated CI/CD pipeline. In the next lesson, we'll get one set up!