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.
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
grabfase publish command takes the following arguments:
- a project 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 project reference is a string of the form
branch is optional. So if your account name is
jdoe, and your project is
jdoe/blog-example is a valid project reference.
When the branch is left out, the CLI assumes you mean the production branch, so
in the previous example, the project reference may be equivalent to
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 descriped 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.