Skip to main content

Single Schema Management

Definitions​

Here are helpful definitions of terms that are used in this document:

  • Instance Schema: The GraphQL schema definition (i.e. schema.graphql) that's deployed in your GraphQL server instance (i.e. typeDefs passed into Apollo Server)
  • Configured Schema: The GraphQL schema definition (i.e. schema.graphql) that's referenced from your Inigo Service YAML definition.

    The Instance Schema and the Configured Schema should have the same exact definition for a given version of the schema, as they should be derived from the same source.

  • Control Plane: Where Inigo Cloud applies, processes, and tracks Inigo configurations, and that tracking includes Configured Schema definitions for your Service.
  • Schema Check Pipeline: Where Inigo Cloud performs the automated validations and checks of the applied Configured Schema.
  • Breaking Change: The Configured Schema has changes that remove or modify parts of the schema that have recently been used by GraphQL clients and may result in client errors if the schema changes are published.

Architecture​

Figure 1 shows the architecture for how Inigo handles single schema deployments with the schema management features. In addition to the Inigo Cloud, the inigo CLI plays an important role for reading and applying the Configured Schema and also performing the schema checking commands.

Note: The Instance Schema is deployed with the GraphQL server, and the GraphQL server is unaware of the Configured Schema that's applied in the Inigo Cloud.

Inigo Architecture, Single Schema
Figure 1. Inigo Schema Management Architecture (Single Schema Configuration)

Set Up a Configured Schema​

To set up a Configured Schema, the Inigo Service contains a schema_files configuration to be set with file path reference. One or more GraphQL schema definition files can be referenced via a relative path (i.e. ../graphql/schema.graphql). If there are more than one referenced files, they will be appended together into one schema definition for the Configured Schema. Example 1 shows a simple example of how to set up the schema_files.

kind: Service
name: single-schema-demo
spec:
  schema_files:
    - ../graphql/schema.graphql

Example 1. Simple Service definition with schema_files.

With the Service and the GraphQL schema definition setup, you can apply the Configured Schema with inigo apply:

inigo apply inigo/service.yaml

Example 2 shows the expected output for this inigo apply.

Service: single-schema-demo

Changelog:
----------
service  created

Steps:
------
Validation:   passed
Composition:  omitted
Operational:  omitted
Evaluation:   passed

New config version 1 is applied 🎉

Check out the report in the UI:
https://app.inigo.io/000/config/activity/1234

Example 2. Expected output of applying a Service definition with schema_files.

Next Steps​

For Single Schema management, Federated Schema and Schema Publishing are not applicable. Please proceed to Schema Checks to learn the details of schema checking.