graphql-schema-registry

Graphql schema storage as dockerized on-premise service for federated graphql gateway server (based on apollo server) as alternative to Apollo studio

Features

• Stores versioned schema for graphql-federated services
• Serves schema for graphql gateway based on provided services & their versions
• Validates new schema to be compatible with other running services
• Provides UI for developers to see stored schema & its history diff
• Stores & shows in UI persisted queries passed by the gateway for debugging

Roadmap

• client tracking (for breaking changes)
• schema usage tracking (for breaking changes)
• separate APQs (use cache only) from backend-registered persisted queries (use DB only)

Installation

Assuming you have nvm & docker installed:

nvm use
npm install
npm run build
docker-compose up --build

Open http://localhost:6001

Configuration

We rely on docker network and uses hostnames from docker-compose.yml. Check app/config.js to see credentials that node service uses to connect to mysql & redis and change it if you install it with own setup. If you use dynamic service discovery (consul/etcd), edit diplomat.js

The following are the different environment variables that are looked up that allow configuring the schema registry in different ways.

Note about NODE_ENV: setting the NODE_ENV environment variable to production will tell the registry to serve web assets (js, css) from their compiled versions in the dist/assets directory.

Use cases

Validating schema on deploy

On pre-commit / deploy make a POST /schema/validate to see if its compatible with current schema.

Schema registration

On service start-up (runtime), make POST to /schema/push to register schema (see API reference for details). Make sure to handle failure.

Architecture

Tech stack

Components

graphql-schema-registry service is one of the components for graphql federation, but it needs tight integration with gateway. Check out examples folder on how to implement it. Note however, that gateway is very simplified and does not have proper error handling, cost limits or fail-safe mechanisms.

DB structure

Migrations are done using knex

Development

DB migrations

To create new DB migration, use:

npm run new-db-migration

If not using the default configuration of executing DB migrations on service startup, you can run the following npm command prior to starting the registry:

npm run migrate-db

The command can be prefixed with any environment variable necessary to configure DB connection (in case you ALTER DB with another user), such as:

DB_HOST=my-db-host DB_PORT=6000 npm run migrate-db

Contribution

• Before making PR, make sure to run npm run version & fill CHANGELOG

Honorable mentions

Original internal mission that resulted in this project consisted of (in alphabetical order):

• aleksandergasna
• ErikSchults
• LexSwed
• tot-ra

Rest API documentation

GET /schema/latest

Simplified version of /schema/compose where latest versions from different services is composed. Needed mostly for debugging

POST /schema/compose

Lists schema based on passed services & their versions. Used by graphql gateway to fetch schema based on current containers

Request params (optional, raw body)

{
  "services": [
    {"name": "service_a", "version": "ke9j34fuuei"},
    {"name": "service_b", "version": "e302fj38fj3"},
  ]
}

Response example

• ✅ 200

{
    "success": true,
    "data": [
        {
            "id": 2,
            "service_id": 3,
            "version": "ke9j34fuuei",
            "name": "service_a",
            "added_time": "2020-12-11T11:59:40.000Z",
            "type_defs": "\n\ttype Query {\n\t\thello: String\n\t}\n",
            "is_active": 1
        },
        {
            "id": 3,
            "service_id": 4,
            "version": "v1",
            "name": "service_b",
            "added_time": "2020-12-14T18:51:04.000Z",
            "type_defs": "type Query {\n  world: String\n}\n",
            "is_active": 1
        }
    ]
}

• ❌ 400 "services[0].version" must be a string
• ❌ 500 Internal error (DB is down)

Request params

• services{ name, version}

If services is not passed, schema-registry tries to find most recent versions. Logic behind the scenes is that schema with highest added_time OR updated_time is picked as latest. If time is the same, schema.id is used.

POST /schema/push

Validates and registers new schema for a service.

Request params (optional, raw body)

{
  "name": "service_a",
  "version": "ke9j34fuuei",
  "type_defs": "\n\ttype Query {\n\t\thello: String\n\t}\n"
}

POST /schema/validate

Validates schema, without adding to DB

Request params (raw body)

• name
• version
• type_defs

POST /schema/diff

Compares schemas and finds breaking or dangerous changes between provided and latest schemas.

• name
• version
• type_defs

DELETE /schema/delete/:schemaId

Deletes specified schema

Request params

GET /persisted_query

Looks up persisted query from DB & caches it in redis if its found

Request params (query)

POST /persisted_query

Adds persisted query to DB & redis cache

Request params (raw body)