Migrating from Apollo

Grafbase and Apollo GraphOS both implement the GraphQL Federation v2 spec. This means you can run a federated graph composed from the same subgraphs using either the Grafbase Gateway or Apollo Router. This guide will assist you in migrating from Apollo to Grafbase.

The major components are comparable:

Additionally, the Grafbase Platform can be fully self-hosted in your own infrastructure for maximum security and control. Contact sales if you want to learn more about the Grafbase Enterprise Platform.

We will explore two scenarios: first, how to run the Grafbase Gateway without migrating any of your GraphOS setup, and second, how to migrate over your federated graph from GraphOS to Grafbase.

If you want to try Grafbase Gateway without migrating your GraphOS setup, you can do so by starting Grafbase Gateway with your existing Federated Graph.

First, you need to install Grafbase Gateway:

curl -fsSL https://grafbase.com/downloads/gateway | bash

Next, you will need the schema of your federated graph. You can download it from the GraphOS Studio UI or via the rover CLI:

rover supergraph fetch my-graph@my-variant > federated.graphql

Now you can start the Grafbase Gateway with your Federated Graph:

grafbase-gateway --schema federated.graphql

You are now up and running! You can send queries to the Grafbase Gateway and see it work with your Federated Graph. To explore all the features and configuration options of the gateway, check out the relevant documentation.

When you are ready for a full migration, you can proceed to the next section. We're also happy to provide assistance, just contact us!

This part of the guide will walk you through setting up your Federated Graph on Grafbase, assuming you already have running subgraphs that have been published to GraphOS.

First, you will need the Grafbase CLI. You can either use npx grafbase or install it with the following command:

curl -fsSL https://grafbase.com/downloads/cli | bash

You can list all your subgraphs as shown in the following example:

rover subgraph list Spotify-Demo-Graph-4m8tpk@current --format=plain
Listing subgraphs for Spotify-Demo-Graph-4m8tpk@current using credentials from the default profile.
┌──────────┬──────────────────────────────────────────────┬────────────────────────────┐
│   Name   │                 Routing Url                  │        Last Updated        │
├──────────┼──────────────────────────────────────────────┼────────────────────────────┤
│ spotify  │ https://showcase-spotify.apollographql.com/  │ 2024-05-06 15:21:54 +02:00 │
├──────────┼──────────────────────────────────────────────┼────────────────────────────┤
│ playback │ https://showcase-playback.apollographql.com/ │ 2024-05-06 15:21:54 +02:00 │
└──────────┴──────────────────────────────────────────────┴────────────────────────────┘

You can pick the subgraphs you want to migrate and publish them manually, or automate the process with a small script.

To publish manually, you can use rover subgraph fetch to download the schema of a subgraph, then grafbase publish to publish it:

rover subgraph fetch Spotify-Demo-Graph-4m8tpk@current > spotify.graphql
npx grafbase publish --schema spotify.graphql --url=https://showcase-spotify.apollographql.com/ --name=spotify

To automate the process, you can use a script like the following:

GRAPHOS_GRAPH_REF=Spotify-Demo-Graph-4m8tpk@current
GRAFBASE_GRAPH_REF=my-account/my-graph@main

rover subgraph list $GRAPHOS_GRAPH_REF --format=json | jq -c '.data.subgraphs[] | {name: .name, url: .url}' > subgraphs.json

while IFS= read -r line; do
  name=$(echo "$line" | jq -r '.name')
  url=$(echo "$line" | jq -r '.url')
  rover subgraph fetch $GRAPHOS_GRAPH_REF --name "$name" > "$name.graphql"
  grafbase publish $GRAFBASE_GRAPH_REF --name "$name" --url "$url" --schema "$name.graphql"
done < subgraphs.json

This takes care of the initial setup.

You should also make sure that you also publish to Grafbase in your release process wherever you already publish to GraphOS with rover subgraph publish. Read more on grafbase publish on the dedicated docs page. This will ensure your subgraphs are up to date on both platforms for the duration of your migration.

Similarly, you should set up schema checks on Grafbase. You can use the grafbase check command to check your schema against the Grafbase Platform. Read more on grafbase check on the dedicated docs page.

Whether you use the binary directly, the official Docker image, or your own preferred deployment method, you can start the Grafbase Gateway with the Federated Graph SDL directly, as in the previous section, or use the graph reference for your gateway to automatically pick up the latest Federated Graph schema whenever it gets published:

GRAFBASE_ACCESS_TOKEN=token ./grafbase-gateway \
  --config grafbase.toml \
  --graph-ref graph@branch

The --config argument is optional, but to start the gateway with a graph ref, the access token is mandatory. You can get an access token from the Grafbase dashboard.

For more information on the features, configuration options, and ways to run the gateway, see the dedicated docs section.

You now have the schema registry populated and the gateway set up. You are running your Federated Graph on Grafbase!

Rover:

rover subgraph publish my-graph@my-variant --name my-subgraph --schema ./my-subgraph.graphql --routing-url https://my-subgraph.example.comjk

Grafbase:

npx grafbase publish my-graph@branch-name --name my-subgraph --schema ./my-subgraph.graphql --url https://my-subgraph.example.com

Rover:

rover subgraph check my-graph@my-variant --name my-subgraph --schema ./my-subgraph.graphql

Grafbase:

npx grafbase check my-graph@branch-name --name my-subgraph --schema ./my-subgraph.graphql