Migrate GraphQL to Hasura

Before You Begin

If you haven't already, Create an account on Hasura's website cloud.hasura.io.

Migrate to Hasura

Migrating your GraphQL API endpoints from MongoDB Atlas App Services to Hasura involves a multi-step process that encompasses setting up your environment in Hasura, configuring database connections, migrating schemas, and implementing authorization and authentication mechanisms. Below is an expanded guide detailing each step, with a focus on authorization and role-based access control (RBAC) within Hasura. For more information, check out the Hasura docs.

To migrate to Hasura:

1. Create a new project in Hasura

2. Authorize Hasura for MongoDB

3. Migrate your GraphQL schema

4. Test your GraphQL queries

5. Handle authorization and authentication

6. Set up custom resolvers

7. Update client applications

8. Shut down MongoDB Atlas App Services

Create a New Project in Hasura

1

After logging in to Hasura, navigate to Projects and create a new project by clicking on New Project. Select a pricing plan, cloud provider, and region that aligns with your MongoDB Atlas setup for optimal performance.

2

After creating your project, take note of the Hasura Cloud IP on this page as you'll use this in your MongoDB Atlas setup to authorize Hasura for MongoDB.

3

Click on Launch Console to open up the Hasura Console.

4

Click on the DATA tab at the top, choose MongoDB from the list of various databases that Hasura supports, and click Connect Existing Database.

Authorize Hasura for MongoDB

Hasura can connect to a new or existing MongoDB Atlas database and generate the GraphQL API for you.

1

Go to cloud.mongodb.com and navigate to the Network Access page on the Atlas dashboard.

2

Click the ADD IP ADDRESS button and enter the Hasura Cloud IP that you obtained from the Hasura Cloud dashboard earlier. Describe this entry as Hasura.

Now, Hasura Cloud can communicate with your MongoDB Atlas instance.

3

On the Database page, find the Atlas cluster that is connected to your App Services app and click on Connect. Select the Drivers option and copy the connection string.

4

Go back to the Hasura Cloud dashboard. On the Connect Existing Database for MongoDB page, enter the name of the MongoDB database you want to connect to and the connection string you copied from the previous step.

5

Click Connect Database. You are finished setting up the connection between Hasura and MongoDB, each hosted on their respective Cloud instances.

Migrate GraphQL Schema

Migrate your MongoDB Atlas GraphQL schema to Hasura's GraphQL schema. This involves defining your types, queries, mutations, and subscriptions in the Hasura Console or the Hasura CLI.

1

In the Hasura console click the Data tab and select your MongoDB database from the left hand pane.

You'll see all the collections from your MongoDB database.

2

To generate a schema for a collection, click on the Track button next to the desired collection.

You have three options to infer the schema of a collection:

• Infer the schema from a sample document you copy and paste from your collection.

• Use Database Schema allows you to use your database's validation schema if one is present in your database (a GraphQL schema will be automatically generated for you).

• Use Existing Logical Model allows you to select a previously created logical model.

3

Click the Validate button to validate the JSON document. In the next step, you will see the models derived from this document. Finally, click the Track Collection button.

Test Your GraphQL Queries

After tracking a collection and getting a schema, you can navigate to the API Explorer page on the Hasura Console to test out some GraphQL queries.

Hasura also uses the GraphiQL interface, which is similar to how you test queries in Atlas App Services.

Authorization and Authentication

Hasura does not directly handle authentication. Instead, it relies on session variables provided by an external authentication service. These session variables include user, role, and organization information crucial for determining data access rights. For details, refer to the Hasura authentication docs

Data access permissions, including roles and rule expressions, can be converted into Hasura role-based permission rules.

All Authentication methods that Atlas provides are compatible with Hasura's Webhook and JWT auth methods. If you are using Email/Pass, Anonymous, or API Key authentication, use Hasura Webhook. If you are using a Custom JWT, integrate directly with Hasura's JWT auth method.

Hasura recommends using an external IdP for managing authentication processes for enhanced security and flexibility. You can integrate Hasura with any authentication provider of your choice, such as Auth0, Firebase Auth, AWS Cognito, or even a custom solution, to verify the user and set the necessary session variables. For configuring JWT or webhook authentication in Hasura, refer to the documentation at:

• JWT Authentication

• Webhook Authentication

Set Up Custom Resolvers

If your existing GraphQL API endpoints include custom resolvers or business logic, you'll need to implement these in Hasura. Hasura supports custom business logic using remote schemas, event triggers, and actions.

Hasura Actions can be used to create custom resolvers. Custom queries and mutations including their payload type and input type can be defined within Hasura, and Hasura can integrate with the resolver function over HTTP.

The resolver function must be deployed somewhere and Hasura can generate the JavaScript code for the function.

Update Client Applications

Update any client applications that interact with your GraphQL API endpoints to point to the new Hasura endpoint URLs. Any existing Apollo client will work with Hasura.

Update the GraphQL operations used by applications to match Hasura-style GraphQL operations.

Shut down MongoDB Atlas App Services Endpoints

Once you have verified that your GraphQL API endpoints are fully migrated and operational on Hasura, you can delete your MongoDB Atlas App Services app to avoid unnecessary costs. As a reminder, Atlas GraphQL endpoints will no longer be supported beginning March 12, 2025.