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
BaaS vs Prisma
Prisma is not a Backend-as-a-Service but a next-generation ORM. This means that it unfortunately can't provide the same level of convenience you're used to from Graphcool. When choosing Prisma for the future of your application, you will have to implement and host your own backend which includes the GraphQL API server as well as the database.
Evolving the application and changing the database schema
Prisma unfortunately doesn't have a production-ready solution for running schema migrations against a database yet. This means that if you migrate to Prisma and want to evolve your application in the future, you'll need to migrate your database schema manually using SQL or another migration tool like Flyway (until Prisma Migrate is considered production-ready).
Implementing an API server (including authentication & authorization)
We recommend using GraphQL Nexus with the nexus-plugin-prisma
to quickly expose GraphQL CRUD operations in your API server without much boilerplate.
However, in case you need to restrict data access in the API with dedicated authorization rules (i.e. permissions queries in Graphcool), this approach won't work and you will have to implement all queries and mutations individually and add your own authorization rules, e.g. using graphql-shield
.
Implementing GraphQL subscriptions
Prisma doesn't have a realtime API that could be used to implement GraphQL subscriptions. Subscriptions can be implemented by manually triggering them inside of a resolver or based on native database triggers.
Upgrade alternatives
Because Graphcool and Prisma 2 are very different, it might be a viable option to migrate to another more BaaS-like provider, such as:
Note: Feel free to reach out to us directly if you have any questions about the migration path.
Migration path
On a high-level, the migration path from Graphcool to Prisma 2 looks as follows:
- Create SQL dump of Graphcool project using the Graphcool Exporter
- Import the dump into a MySQL database
- Introspect your database with Prisma 2.0
- 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:
schema.prisma
1model Category {2 id String @id3 name String4 Post Post[] @relation(references: [id])5}67model Post {8 authorId String?9 content String?10 createdAt DateTime @default(now())11 id String @id12 published Boolean @default(false)13 title String14 updatedAt DateTime @default(now())15 Category Category[] @relation(references: [id])16}1718model Profile {19 bio String?20 id String @id21 user String? @unique22 User User? @relation(fields: [user], references: [id])23}2425model User {26 email String? @unique27 id String @id28 jsonData Json?29 name String30 role User_role? @default(CUSTOMER)31 Profile Profile?32}3334enum User_role {35 ADMIN36 CUSTOMER37}
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()},})