Publishing a subgraph

The federated graph's schema is not managed directly: the schema registry produces it by composing the schemas of subgraphs. You compose the federated graph's schema by publishing subgraphs.

The grafbase publish command can be used in two contexts: with a deployed schema registry and in the local development workflow. In this page, we will concentrate on the regular workflow that interacts with the Grafbase API.

The grabfase publish command takes the following arguments:

• a graph reference positional argument (required)
• --schema (optional): the file path of the GraphQL schema you want to publish. If the argument is not provided, the CLI will try to read the schema from stdin.
• --url (optional): the url of the endpoint serving the subgraph you are publishing. This argument is only required the first time a subgraph is published. If not provided, the url is assumed to be the same as the currently published version's.
• --name (required): the name of the subgraph to publish.

A graph reference is a string of the form account/graph@branch. The branch is optional. So if your account name is jdoe, and your graph is called blog-example, then jdoe/blog-example is a valid graph reference.

When the branch is left out, the CLI assumes you mean the production branch, so in the previous example, the graph reference may be equivalent to jdoe/blog-example@main.

The CLI commands that interact with the schema registry all take a project reference as a first argument.

It generally makes sense to publish a subgraph schema every time you deploy a new version of the subgraph. Publishing an already published schema again without changes is safe, it has no side effects.

As described in Composition however, publishing an updated subgraph schema has side effects:

• Composition may fail, and the federated graph's schema will not be updated until you fix the composition errors.
• Composition succeeds, and the federated graph's schema is updated, but your changes break existing client (for example, when you remove a field or change its type).

To avoid disruption, Schema Checks are there to verify that publishing your new or updated schema is safe.