Migrate from Graphcool to Hasura

Graph.cool will be sunsetted July 1, 2020. If you have an existing project, it is time to migrate off from their platform to have enough leeway for testing and going production.

I have been helping a few folks migrate from Graph.cool to Hasura and decided to put together a rough migration path.
Hasura is an open source engine that connects to your databases & microservices and auto-generates a production-ready GraphQL backend.

Pre-requisites:

We will be using docker to run some containers (MySQL, Postgres and Hasura). If you don't have docker on your machine yet, it is time to set up. Read their official docs

Note: This guide is not comprehensive and some steps require manual intervention depending on your Graph.cool project. Feel free to ask any queries in the comments. You can also DM me on Twitter. I will be happy to help you out :)

But here's roughly what you need to follow to get going.

Step 1: Export data from Graph.cool

Export your Graph.cool data using their export tool. This will give a MySQL binary dump of your current Graphcool data.

Step 2: Set up an intermediary MySQL server

We need to set up a MySQL server as an intermediary step in order to migrate data from Graph.cool to Postgres.

Step 2.1: Start MySQL with Docker

docker run --name graphcool-mysql -e MYSQL_ROOT_PASSWORD=my-secret-pw -p 3306:3306 -d mysql:latest --default-authentication-plugin=mysql_native_password

Replace the password (my-secret-pw) as required.

Step 2.2: Connect to MySQL via mysql CLI

mysql --user=root --password=my-secret-pw --host=<host>

Replace the host and password as required.

Step 2.3: Create a database in MySQL

create database public;

Step 2.4: Import data

Import Graph.cool's MySQL export into your local MySQL instance:

mysql --user=root --password=my-secret-pw --host=<host> public --binary-mode=1 < <pathtomysqlexport>

Replace host and pathtomysqlexport as required. Your data should now be present in the MySQL database.

Step 3: Migrate data to Hasura

Since MySQL is now set up with all the data from Graph.cool, we need to create a Hasura and Postgres instance, and to import the data to the same.

Step 3.1: Set up Hasura

Refer to the Getting started guide to set up Hasura using docker-compose.

Step 3.2: Import data into Postgres

We will use pgloader to migrate from MySQL to Postgres. Refer to their installation guide for setting this up.

Once you have installed, execute the following command:

pgloader mysql://root:my-secret-pw@<host>/public postgresql://postgres:postgrespassword@<host>:5432/postgres

Replace <host> and mysql password (my-secret-pw) as required.

Your data should now be present in the Postgres database.

Step 3.3: Connect Hasura to Postgres

Once the dataset is migrated to Postgres, Hasura should be able to track tables and relationships.

Note: If you have enums in your Graph.cool project, check out Enums in Hasura, since they're handled differently in Hasura and you would need to change the data structure a bit.

Step 4: Migrate structure & functionality

After migrating the data to Hasura, there is some manual work involved in migrating the structure and functionality of your Graph.cool project.

Step 4.1: Restructure connection tables

You can rename tables/columns to match your client-side queries as required. Do note that, for every one-to-one relationship, Graph.cool would have created a connection table to link them. This would require a bit of manual work to restructure. Currently, there is no automation available for this step. Carefully review the connection tables and make the necessary changes.

Read up more about Relationships in Hasura

Step 4.2: Migrate functions

In case you have functions in Graph.cool, Hasura has an equivalent feature called Event Triggers. Migrating this involves taking your code and deploying it on a different platform. It could be a serverless function or all the functions can be combined into a monolith Node.js server. The choice is up to you.

Do note that for event triggers, the payload that Hasura sends might be different, and you might have to change the way the request body parameters are handled in your function code.

Step 4.3: Migrate auth

There are two ways of authenticating users in Graph.cool:

1. Using Auth0
2. Using email-password auth.

If you were using Auth0 with Graph.cool, the migration should be fairly straightforward. You can configure Hasura with Auth0 easily by following the Auth0 guide.

In case you are using email-password auth, Graph.cool generates mutations for

• creating a user

createUser(authProvider: { email: { email, password } })

• login

signinUser(email: { email, password })

You will need to implement these custom mutations using Hasura Actions.
Refer to this example for a custom signup mutation. You can modify this to include login functionality.

Step 4.4: Migrate permissions

The CRUD permissions in Graph.cool can be manually migrated to Hasura's permission system. You can define roles in Hasura and configure permissions declaratively for all the CRUD operations.
Refer to authorization for configuring Hasura permissions.

Community Tooling for File Storage

Nhost has a community maintained solution hasura-backend-plus for handling Files on Cloud providers like S3 in case you are looking for a way to migrate Files from Graph.cool. They also have an Auth solution that can be integrated with Hasura :)

Subscriptions

Hasura gives you realtime APIs out of the box. All your Postgres tables can be subscribed from the client using GraphQL Subscriptions.

I hope this guide gives an indication of the steps involved. In case you are stuck with any of the steps, do ping me :)

Hasura has an active and a helpful discord community. Do join the discord server as well and post your queries.