graphql-tools difference between mergeSchemas and makeExecutableSchema

Question

So the reason I am asking this question is because I can get both of these to return a working result with just replacing one or the other. So which is the right one to use and why?

What are their purposes in regards to schemas?

import { mergeSchemas } from 'graphql-tools'

import bookSchema from './book/schema/book.gql'
import bookResolver from './book/resolvers/book'

export const schema = mergeSchemas({
    schemas: [bookSchema],
    resolvers: [bookResolver]
})

import { makeExecutableSchema } from 'graphql-tools'

import bookSchema from './book/schema/book.gql'
import bookResolver from './book/resolvers/book'

export const schema = makeExecutableSchema({
    typeDefs: [bookSchema],
    resolvers: [bookResolver]
})

Both of these examples work and return the desired outcome. I believe the correct one to use here is the makeExecutableSchema but not sure why the first one would work?

EDIT Just incase it would be nice to have the types/resolvers:

typeDefs

type Query {
    book(id: String!): Book
    bookList: [Book]
}

type Book {
    id: String
    name: String
    genre: String
}

Resolvers

export default {
    Query: {
        book: () => {
            return {
                id: `1`,
                name: `name`,
                genre: `scary`
            }
        },
        bookList: () => {
            return [
                { id: `1`, name: `name`, genre: `scary` },
                { id: `2`, name: `name`, genre: `scary` }
            ]
        }
    }
}

Query Ran

query {
  bookList{
    id
    name
    genre
  }
}

Result

{
  "data": {
    "bookList": [
      {
        "id": "1",
        "name": "name",
        "genre": "scary"
      },
      {
        "id": "2",
        "name": "name",
        "genre": "scary"
      }
    ]
  }
}

score 3 · Accepted Answer · edited Sep 15 '20 at 04:22

mergeSchemas is primarily intended to be used for schema stitching, not combing code for a single schema you've chosen to split up for organizational purposes.

Schema stitching is most commonly done when you have multiple microservices that each expose a GraphQL endpoint. You can extract schemas from each endpoint and then use mergeSchemas to create a single GraphQL service that delegates queries to each microservice as appropriate. Technically, schema stitching could also be used to extend some existing API or to create multiple services from a base schema, although I imagine those use cases are less common.

If you are architecting a single, contained GraphQL service you should stick with makeExecutableSchema. makeExecutableSchema is what actually lets you use Schema Definition Language to generate your schema. mergeSchemas is a relatively new API and has a number of open issues, especially with regards to how directives are handled. If you don't need the functionality provided by mergeSchemas -- namely, you're not actually merging separate schemas, don't use it.

Note that within the newer versions of GraphQL tools, the stitching function has been renamed `stitchSchemas` while `mergeSchemas` now does what you would expect, merging schemas directly without a proxy layer, (based on the functionality from GraphQL toolkit). The API for schema stitching has been much improved, but you should still avoid adding a proxy layer (if you don't need to). — Yaacov, Jan 06 '21 at 10:57

score 0 · Answer 2 · answered Aug 10 '20 at 20:48

Yes makeExecutableSchema creates a GraphQL.js GraphQLSchema instance from GraphQL schema language as per graphql-tools docs So if you are creating stand alone, contained GrpaphQL service is a way to go.

But if you are looking to consolidate multiple GraphQL services there are multiple different strategies you may consider such as schema-stitching, schema-merging from graphql-tools or federation from apollo (there are probably more).

Since I landed here while searching what is the difference between stitching and merging I wanted to point out that they are not one and the same thing. Here is the answer I got for this question on graphql-tools github.

score 0 · Answer 3 · answered Dec 28 '20 at 01:00

Schema Stitching creates a proxy schema on top of different independent subschemas, so the parts of that schema are executed using GraphQLJS internally. This is useful to create an architecture like microservices.

Schema Merging creates a new schema by merging the extracted type definitions and resolvers from them, so there will be a single execution layer.

The first one keeps the individual schemas, but the second one won't. A use case for the first would be for combining multiple remote GraphQL APIs (microservices), while the second one would be good for combining local schemas.

graphql-tools difference between mergeSchemas and makeExecutableSchema

3 Answers3