Moving from Self Hosted Hasura OSS to Hasura Cloud

We recently announced the launch of Hasura Cloud that takes care of managing the GraphQL Infrastructure automatically for you, so that you can focus on building your apps and not worry about Infrastructure. If you are running Hasura OSS, it's fairly straigtforward to migrate to Hasura Cloud. We will look at why and how to migrate in this post and the benefits it brings along.

Why migrate to Hasura Cloud?

Hasura Cloud uses the OSS graphql-engine as the base and provides a cloud offering on top of that. Broadly there are two benefits to move your OSS instance to Hasura Cloud.

• Infrastructure concerns like number of instances, cores, memory, concurrent users, high-availability, realtime monitoring and tracing are taken care of, automatically for you.
• GraphQL Server concerns like data caching, rate-limiting, regression testing, error monitoring are some of the features that will be useful at scale.

With Hasura Cloud, GraphQL becomes the invisible piece in your architecture. Auto-scaling kicks in if you have a sudden traffic rush and eventually the only bottleneck will be the database. To optimise for database bottlenecks, Hasura Cloud gives you monitoring and tracing features that help you understand database query performance and give you insight into what to do.

You will also have the ability to add collaborators to your team per project and give restricted access to the console and server operations among other benefits.

Read more in detail about the benefits of Hasura Cloud in our announcement post.

Now that you know the benefits of migrating, let's quickly look at the steps required in performing the migration. The process depends on where your current Hasura instance is running and where your database is hosted. Do remember that, the database will still remain hosted the same way as before and doesn't need any migration apart from a potential configuration update like IP whitelisting. It is only the graphql-engine OSS server that needs to be migrated to Hasura Cloud.

Migration Steps

Note: If you are running Hasura OSS in production, you can follow all of the steps below on your staging server first and recommend moving your production workload to Hasura Cloud once it reaches general availability.

Step 1: Update your current Hasura OSS GraphQL server to the latest version.

Any new project created via Hasura Cloud runs on the latest version of Hasura OSS. At the time of writing this guide, the latest version of Hasura OSS is v1.3.0 and the docker image for the same is hasura/graphql-engine:v1.3.0. Change yours accordingly. Before migrating, we need to ensure OSS server is on the latest version to avoid any inconsistencies in metadata and configuration. Read more on how to update your current Hasura instance.

Step 2: Take a database backup and metadata snapshot.

Although updating to Hasura Cloud will only touch the internal schema that the server maintains in the database, it's a good practice to take a backup before any migration. Use pg_dump CLI tool or the PG Dump API to take a backup of your database and take a snapshot of your metadata using the Hasura CLI. ie. hasura metadata export. Read more on metadata export.

Step 3: Find the postgres connection string for your existing database.

We need to keep the database connection URL handy before creating a project on Hasura Cloud. This would look something like postgres://username:password@hostname:port/dbname

Usually the HASURA_GRAPHQL_DATABASE_URL env of your existing OSS instance should have the right values if you are using any of the cloud database vendors like the Google Cloud SQL, RDS, Azure Postgres etc.

But if the database is not exposed to the outside world and the server is hosted on the same cluster as the database, accessing db via internal network, then you need to expose the database on a port which is accessible from outside that server. Support for VPC Peering will be added soon which lets you access database not exposed over internet.

For example, if you are running Hasura OSS on a DigitalOcean droplet, usually created via the One-Click integration on their marketplace, then the Postgres instance is not exposed outside. In this case, you will need to modify the docker-compose file to run the db and expose on a port (for example: 5432). DigitalOcean has Firewall Rules that can be setup to limit who can access what ports.

Below is an example from Google Cloud Platform to whitelist an IP to authorize access.

We will find what IP to whitelist after creating the project on Hasura Cloud.

The whitelisting IP step varies depending on the cloud vendor where your database is hosted currently and I would recommend checking official docs of the Cloud provider to configure this.

Step 4: Keep the HASURA_GRAPHQL_* environment variables ready

Depending on where Hasura OSS is hosted, fetch all the Hasura environment variables and their values used for the server. If it's a docker-compose file, then all envs used would be present there. If it's a kubernetes cluster, check the deployment.yaml for the env used.

Note: If you are passing server flags to the OSS server, make sure to find the equivalent environment variable from the docs and keep them handy.

Step 5: Configure necessary Postgres permissions

This step is optional and applicable only if your database is running in a controlled environment, where you might need to configure Hasura Cloud to use a specific Postgres user that your DBA gives you.

Read more about Postgres permissions required for running Hasura Cloud.

Step 6: Create a new project on Hasura Cloud.

Now that all configurations are ready, we can move on to the project creation step. Click on the Deploy to Hasura button below, signup for free to create a new project.

<!--kg-card-begin: html--><!--kg-card-end: html-->

In the new project page, enter the Database URL that was obtained from Step 3.

Note the IP address given in the Allow connections to your database from Hasura Cloud IP box. Copy that and add this IP to Whitelist in your server / database vendor as mentioned in Step 3.

Once you click on Create project, your project will be initialised and ideally after a few seconds you should get the Launch Console button enabled for the project.

Step 7: Configure Environment variables

This is the final step of the migration process. Once the Cloud project is initialised, click on the Env vars tab on the project detail page.

To add a new environment variable, click on New Env Var and it should open up the following screen:

Add all the environment variables obtained from Step 4 to your Cloud project. You can ignore the HASURA_GRAPHQL_DATABASE_URL and HASURA_GRAPHQL_ADMIN_SECRET environment variables since that's already configured. In case you are using the old admin secret in other backend servers / APIs, you can update that env here so that those APIs don't break.

Verify and test the migration

That's it! You should be able to access the Hasura Console and make all your API requests to the new endpoint from your app. You can monitor the requests and see if queries are failing from the Pro tab of the console.

Local to Cloud

What if there is an instance of Hasura running on local environment? Migrating this to Hasura Cloud will involve additional steps, primarily around setting up the database itself.

• You need to setup the database somewhere (Either on Heroku Postgres via One-Click integration on Hasura Cloud, or via other cloud vendors).
• All of the steps mentioned above for migration would apply for local to cloud migration too.
• Once the cloud project is created, if you have the migrations and metadata ready for your local instance, apply them to the cloud project using the Hasura CLI via hasura migrate apply and hasura metadata apply.
• If you don't have the migrations ready or didn't use the Console via CLI for migrations in your local dev, you can make use of the PG Dump API to export the local database schema and apply it to the new database created as the initial migration file. The metadata can be exported from your local db by using hasura metadata export.
• Follow the Production Checklist to ensure your local instance is ready to go live.

Things to Note:

• Custom domains will be added soon to Hasura Cloud. This will let you configure your own domain for the API endpoint instead of the auto-generated hasura.app endpoint.
• Moving from Hasura OSS to Hasura Cloud (and vice-versa) is reversible as long as the server version connecting to the database remains the same on both.
• You can create the project, apply the environment variables via an API too. Read more on the API reference.

Let us know how the migration went through! In case you want help to troubleshoot/debug, feel free to join our Discord server and post your queries over there.