Migrating from Hasura v1.3 to v2.0

Hasura 2.0 was announced last month with significant changes inside the GraphQL Engine. But we have made sure that user facing APIs didn't go through a breaking change for this release. There are fundamental changes like managing multiple data sources and additional support for generating REST APIs.

In this post, we will look at how to migrate from Hasura v1.3 to the latest 2.0 version in different scenarios.

What's new in v2?

Before we get started, let's look at what's new in v2. With support for multiple databases, you are no more constrained in connecting to just one Postgres db. You can now connect to multiple Postgres DBs or even different databases like SQL Server (and other databases in the future). So broadly,

• Multiple databases can be connected to Hasura for generating APIs.
• The metadata is stored in Postgres and can be configured using HASURA_GRAPHQL_METADATA_URL pointing to a Postgres DB. The difference in v2 is that, this can now be a separate Postgres DB, different from your application db where you create and manage your models and data.
• In Hasura Cloud, the metadata database is provisioned and automatically taken care.

Updating: Backwards Compatibility Mode

Hasura GraphQL Engine in versions <= v1.3.x uses the ENV variable HASURA_GRAPHQL_DATABASE_URL for connecting to the Postgres database. In Hasura 2.0, you can continue to use this env and update your self hosted instance. In this mode, the same Postgres DB will be used as a source for the metadata database as well.

For self-hosted OSS Hasura GraphQL Engine, you can update the docker image to point to the latest version and everything will continue to work.

The latest docker image at the time of writing this:

hasura/graphql-engine:v2.0.0-alpha.4

Use this image in your docker-compose.yaml or any other setup where Hasura is running currently.

In case you are using Hasura Cloud, do note that the updates will be rolled out automatically to all existing instances. But if you wish to do it yourself before the rollout happens, you can read the section below on Updating on Hasura Cloud.

Migrations and Metadata

Hasura 2.0 fundamentally changes a few things and requires a change in the way metadata and migrations are managed using the CLI. A new config version v3 is introduced for managing migrations and metadata.

Pre-requisite: Update Hasura CLI

The latest version of Hasura CLI (at the time of writing this post) is 2.0.0-alpha.4. If you are using an older version of CLI, something like 1.3.3 then you will have to update the CLI as the first step.

hasura version

Run the following command to update the cli to the latest version.

hasura update-cli --version v2.0.0-alpha.4

Upgrade Hasura Project to v3 Config

In the project directory of Hasura, run the following command:

hasura scripts update-project-v3

This would update the existing v2 config project structure to v3 config. The metadata directory looks something like this:

metadata
├── actions.graphql
├── actions.yaml
├── allow_list.yaml
├── cron_triggers.yaml
├── databases
│ ├── databases.yaml
│ └── default
│ ├── functions
│ │ ├── functions.yaml
│ │ └── public_search_artists.yaml
│ └── tables
│ ├── public_albums.yaml
│ └── tables.yaml
├── query_collections.yaml
├── remote_schemas.yaml
├── rest_endpoints.yaml
└── version.yaml

There is a new directory called databases which contains metadata about the different dbs connected to the project and all the tables put into their individual yaml files.

The migrations directory gets an update as well. Each database gets a child directory inside migrations and the relevant up.sql and down.sql files will be inside these.

migrations
└── default
  └── 1613987232674_init
      └── up.sql

Applying Migrations and Metadata

In order to apply the metadata that's exported from an existing project, you can continue to use the same command that was used earlier:

hasura metadata apply

On the other hand, the migration apply needs a database flag.

hasura migrate apply --database default

Upgrading on Hasura Cloud

All new projects created on Hasura Cloud will be using v2.0 (currently in alpha).

Existing projects running on v1.3.x will be updated automatically to v2.0 in the coming days. But in case it is required earlier than that, you can manually create a new cluster and point your old postgres db to the new instance of Hasura.

Once a new project is created, and the Hasura project is updated to config v3, you can point the old database connection string and everything should continue to work.

Things to Note:

During the migration, it is important to first update the Hasura server to the latest version before touching anything related to migrations and metadata. The config v3 will only work with the latest Hasura v2.0 server and anything else will throw an error.

If you are changing the name of the database source (either via console or via metadata), you also need to ensure that it is changed in the migrations directory as well to make sure the the CLI commands continue to work for applying the migrations.