Follow-along: Schema checks & deploy

🤔 The situation: We want to clean up our schema. We want to remove a recipe's prepTime field.

Remove fields

1. Open up schema.graphql, find the prepTime field. Delete the field, along with its description (the line in quotation marks above the field).

   schema.graphql

   - "How much time it takes to prep the ingredients, in minutes"
   - prepTime: Float

   Copy

   Note: We don't recommend removing a field all in one go like this! In the next step, we'll use schema checks to help catch potential breaking changes like this, then follow the recommended best practices after.

2. Grab the graph reference for our supergraph. We can find this value in Studio, at the top of the graph's README page.

   https://studio.apollographql.com

   

3. Open up a new terminal and paste in the rover subgraph check command. Make sure you replace the parameters with your own values.

   rover subgraph check poetic-plates-supergraph@main \
    --name recipes \
    --schema schema.graphql

   Copy

   In the Rover output, we'll see a table of the changes. The first column indicates whether each change passed or failed the check. The second column indicates the type of change we made, such as FIELD_ADDED and FIELD_DEPRECATED. The last column provides a more detailed description of the change, such as what exact type was created and what field was added under the type.

Best practice for removing fields

We need to give clients enough time to address these field removals. Here's the process for removing fields in our schema:

1. Mark fields as deprecated using the @deprecated directive and push these changes.
2. Let clients know proactively through appropriate channels (GraphOS Explorer will also start showing deprecated warnings)
3. Monitor usage of the deprecated fields.
4. After some time has passed, delete the field from the schema.

Mark fields as deprecated

1. Open up schema.graphql and undo your changes so that the prepTime field and description are back in the schema. Add the @deprecated directive with a reason for deprecation.

   schema.graphql

   "How much time it takes to prep the ingredients, in minutes"
   prepTime: Float @deprecated(reason: "Use consolidated readyTime")

   Copy

2. In a terminal window, run the schema check again.

   rover subgraph check <GRAPH_REF> \
     --name recipes \
     --schema ./schema.graphql

   Copy

3. It should be passing now! In the terminal, run npm start to get the subgraph server running (if it's not running already).

4. Open up Sandbox at http://localhost:4001, where the subgraph server is running.

5. Try building a query for a random recipe's name and prepTime.

   query GetRecipeTimes {
     randomRecipe {
       name
       prepTime
     }
   }

   Copy

Deploying changes

We'll commit our changes and push them up to our GitHub repo's main branch. This will trigger an automatic deploy to Railway.

Feel free to use any tool you're comfortable with to work with Git! We'll use terminal commands.

1. Open up a new terminal.

2. Add the files we've changed.

   git add schema.graphql

   Copy

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

   git commit -m "Deprecate prepTime."

   Copy

4. Push the changes to the GitHub repo.

   git push -u origin main

   Copy

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!

Check your understanding

☕ BREAK (15 minutes)

When you come back, ensure that your deploy was successful.