Publishing schemas to GraphOS

Whenever you make changes to a graph's schema, you should publish those changes to Apollo GraphOS using the Rover CLI or the Platform API. Doing so ensures that Apollo always has an up-to-date understanding of your graph.

This page covers how to publish different kinds of schemas using the Rover CLI. Consult the Platform API reference to learn how to use the API for publication.

Prerequisites

1. Install the Rover CLI.
2. Authenticate Rover with GraphOS.

Publish subgraph schemas

Every supergraph in GraphOS includes one or more subgraphs. These are the individual GraphQL-powered microservices in your organization.

You individually publish each subgraph's schema to Apollo with rover subgraph publish:

rover subgraph publish --schema ./products.graphql --name products docs-example-graph@current --routing-url https://products.example.com

To publish a subgraph schema to Apollo:

1. Identify the name of the subgraph you're publishing to. You can view the names of your existing subgraphs from your variant's Subgraphs page in GraphOS Studio.

2. If you're publishing a subgraph for the first time, also obtain the routing URL of that subgraph. This is the URL that your router will use to communicate with the subgraph.

   • If GraphOS already knows your subgraph's routing URL, you don't need to provide this value unless you're changing it.

3. Run the rover subgraph publish command and provide it your subgraph's schema in one of the ways shown:

   Bash

   # Provide a local .graphql file path
   rover subgraph publish my-graph@my-variant --name locations --routing-url https://flyby-locations-sub.herokuapp.com/ --schema ./schema.graphql
   
   # Provide an introspection result via stdin
   rover subgraph introspect http://localhost:4000 | rover subgraph publish my-graph@my-variant --name locations --routing-url https://flyby-locations-sub.herokuapp.com/ --schema -

   Copy

Whenever you publish a subgraph schema, GraphOS attempts to compose all latest versions of your subgraph schemas into a single supergraph schema for your router:

If this composition succeeds, your router is updated with the result. This enables clients to query any newly added fields, and it prevents them from querying any removed fields.

You can manually fetch your router's latest supergraph schema with the rover supergraph fetch command, or retrieve it from your supergraph's Schema > SDL page in GraphOS Studio.

Publish monograph schemas

1. Decide how you'll provide your server's schema to Rover. You can either:

   • Use a .gql or .graphql file saved on your local machine, or
   • Perform an introspection query on your running server to fetch the schema

2. Run the rover graph publish command, providing your schema in one of the ways shown:

   Bash

   # Provide a local .graphql file path
   rover graph publish my-graph@my-variant --schema ./schema.graphql
   
   # Provide an introspection result via stdin
   rover graph introspect http://localhost:4000 | rover graph publish my-graph@my-variant --schema -

   Copy

   As shown, the first positional argument you provide rover graph publish is a graph ref, a string that specifies a particular variant of a particular graph in GraphOS.

Publish with continuous delivery

To get the most out of GraphOS, you should publish each update to any production schema as soon as it occurs. Consequently, schema publishing should be part of your continuous delivery pipeline.

Here's a sample continuous delivery configuration for schema publishing in CircleCI:

1
version: 2
2

3
jobs:
4
  build:
5
    docker:
6
      - image: circleci/node:8
7

8
    steps:
9
      - checkout
10

11
      - run: npm install
12

13
      - run:
14
          name: Install Rover
15
          command: |
16
            # Download and install Rover
17
            # This is pinned to a specific version for predictability in CI
18
            curl -sSL https://rover.apollo.dev/nix/v0.8.1 | sh
19

20
            # This allows the PATH changes to persist to the next `run` step
21
            echo 'export PATH=$HOME/.rover/bin:$PATH' >> $BASH_ENV
22

23
      # Start the GraphQL server.  If a different command is used to
24
      # start the server, use it in place of `npm start` here.
25
      - run:
26
          name: Starting server
27
          command: npm start
28
          background: true
29

30
      # make sure the server has enough time to start up before running
31
      # commands against it
32
      - run: sleep 5
33

34
      # When running on the 'main' branch, push the latest version
35
      # of the schema to GraphOS.
36
      - run: |
37
          if [ "${CIRCLE_BRANCH}" == "main" ]; then
38
            rover subgraph publish my-graph@my-variant \
39
              --schema ./schema.graphql \
40
              --name locations \
41
              --routing-url https://products.example.com
42
          fi