Upgrade from Graphcool

Overview

This guide explains how to upgrade from Graphcool to Prisma 2.

Note: The Graphcool servers have been shut down on July 1st. Please reach out to us if you have any further questions.

Considerations before upgrading

Migration path

On a high-level, the migration path from Graphcool to Prisma 2 looks as follows:

1. Create SQL dump of Graphcool project using the Graphcool Exporter
2. Import the dump into a MySQL database
3. Introspect your database with Prisma 2.0
4. Create CRUD GraphQL API with Nexus (and optionally nexus-plugin-prisma)

1. Create a SQL dump of your Graphcool project

Open the Graphcool Exporter at https://export.graph.cool/.

Then grab your permanent auth token from the Settings > Authentication > Permanent Auth Tokens area in the Graphcool console and paste it into the text field. Now click Export.

This downloads a zipped .sql file with a dump of all the data that's stored in your Graphcool project.

2. Import the SQL dump into your own MySQL database

Follow the guide that explains how to import data into a MySQL database.

3. Introspect your database with Prisma 2

At this point, you have a MySQL database with the same data that you had in your Graphcool project. You can now setup your new npm project that you'll use to implement the GraphQL API:

npm init -y

With your new npm project in place, you can follow the guide that explains how to add Prisma to an existing project.

Note that Graphcool uses the same data modeling approach as Prisma 1. If you encounter any schema incompatibilities, you can resolve them in the same way as if you were upgrading from Prisma 1.

4. Create CRUD GraphQL API

The last step in the migration process is to expose CRUD operations in your GraphQL API. The recommended approach for this is to use Nexus and the nexus-plugin-prisma. The plugin allows you to directly expose your Prisma models via GraphQL.

Once you installed the required dependencies in your project, you can add the nexus-plugin-prisma as follows:

import { use } from 'nexus'
import { prisma } from 'nexus-plugin-prisma'
use(prisma({ migrations: false }))

The last line gives you access to the t.model and t.crud fields when defining your GraphQL schema with Nexus. Both fields enable you to

Here is an example, assume you have the following Prisma schema:

model Category {
  id   String @id
  name String
  Post Post[] @relation(references: [id])
}
model Post {
  authorId  String?
  content   String?
  createdAt DateTime   @default(now())
  id        String     @id
  published Boolean    @default(false)
  title     String
  updatedAt DateTime   @default(now())
  Category  Category[] @relation(references: [id])
}
model Profile {
  bio  String?
  id   String  @id
  user String? @unique
  User User?   @relation(fields: [user], references: [id])
}
model User {
  email    String?    @unique
  id       String     @id
  jsonData Json?
  name     String
  role     User_role? @default(CUSTOMER)
  Profile  Profile?
}
enum User_role {
  ADMIN
  CUSTOMER
}

Here's how you can ensure all your models are exposed via GraphQL:

schema.objectType({
  name: 'User',
  definition(t) {
    t.model.id()
    t.model.email()
    t.model.name()
    t.model.jsonData()
    t.model.role()
    t.model.profile()
    t.model.posts({
      filtering: true,
      ordering: true,
    })
  },
})
schema.objectType({
  name: 'Post',
  definition(t) {
    t.model.id()
    t.model.createdAt()
    t.model.updatedAt()
    t.model.title()
    t.model.content()
    t.model.published()
    t.model.author()
    t.model.authorId()
    t.model.categories({
      filtering: true,
      ordering: true,
    })
  },
})
schema.objectType({
  name: 'Profile',
  definition(t) {
    t.model.id()
    t.model.bio()
    t.model.user()
    t.model.userId()
  },
})
schema.objectType({
  name: 'Category',
  definition(t) {
    t.model.id()
    t.model.name()
    t.model.posts({
      filtering: true,
      ordering: true,
    })
  },
})

Finally, you can expose CRUD operations for all your models via t.crud when defining your Query and Mutation types with Nexus. For example, if you want to enable all the CRUD operations for the User model, you can do it as follows:

schema.queryType({
  definition(t) {
    t.crud.user()
    t.crud.users({
      pagination: true,
      filtering: true,
      ordering: true,
    })
  },
})
schema.mutationType({
  definition(t) {
    t.crud.createOneUser()
    t.crud.updateOneUser()
    t.crud.deleteOneUser()
  },
})