What's the best practice to migrate fields to a different subgraph

API Design, Strategy & Governance
,
1

hi team,

I’m just coming across an issue now when I want to migrate field from my subgraph to a different one.

I understand override directive is the suggested approach.

However my case is a bit different.

The field I want to migrate is a field with requires directive that means it’s a field that I’m contribute to the other subgraphs.

So I can’t use the override approach now.

The difficulty now is:
1, the field is consumed by the clients in prod.

  1. A new subgraph needs to implement the field
  2. I can’t remove the field from my subgraph because it will break our clients in prod.

What would be the suggested approach in my case?

Thank you!

1 Like
2

I’m confused about why @requires is preventing the use of @override. Can you provide example schemas that demonstrate this?

3

That’s because @override cannot be used with @external, @requires, or @provides.

Take a look: Apollo Federation Error Codes - Apollo GraphQL Docs

@Jesse If you’re using Managed Federation, you don’t need to worry too much about field availability since Uplink takes care of that.

So, if you are using Managed Federations, first you can deploy the new subgraph with the field you want to move. You’ll get a composition error, but as I said, don’t worry, the supergraph will still serve the old version. Then, just go to the old subgraph, remove the field, and publish again.

Uplink doc:

Without Managed Federation, you need to restart the router and ensure the availability of both the supergraph and subgraphs during the rollout, but you already know that.

Another alternative is to create a new field and deprecate the previous one, but it can be a problem.

That being said, I’m curious to hear about other alternatives from the Apollo team.

1 Like
4

Thank you @michaeldouglasdev for your answer.

I’m very keen to know more details about your solution as it’s a very new area to me. I have had a look at the uplink doc and the advanced deployment workflow.

We are using Managed Federation and we have only one prod environment.

Our currently deployment workflow is basically that each team publishes their own subgraph schema to the router and service gets deployed to prod individually.

To the solution you mentioned, I have some more questions if you don’t mind.

  1. we do get a composition error, how do we publish the schema to the router?
  2. would you elaborate what the deployment workflow will look at?

Thank you!

5

You’re very welcome! I’d glad to help.

We do get a composition error, how do we publish the schema to the router?

  • If a subgraph introduces a schema conflict (e.g., the same field defined in two subgraphs), Apollo Uplink will reject the composition, meaning the supergraph won’t update. If you deploy the new subgraph, you will able to see this subgraph in the Graph OS, but it will not get any request, the router will be using the supergraph with stable version (without composition error).
  • The existing supergraph (production) schema remains available, so clients won’t experience any downtime.
  • The key here is that the router keeps serving the last successfully composed schema until a valid update is published.
  • Always remember that the existing production version will remain if a composition error occurs, but the uplink will store the new version.

would you elaborate what the deployment workflow will look at?

My suggestion:
1- Publish the new subgraph. Here you will receive a composition error, but its not a problem. As a said before, the production supergraph will be remain.
2- Remove the field from the old subgraph and publish the update.

The Uplink will merge the last version (composition error version) with this new version (old subgraph without field)

Now, the router will route requests to the new subgraph when this field is requested.

1 Like
6

Awesome! This is very detailed and it’s super helpful! Exactly what I’m looking for.
Thank you very much!