Upgrading to Hasura migrations config v2

What has changed?

In config v1, the PG schema migrations and Hasura metadata were both handled using the same migration files which were in yaml format. In config v2, these are managed separately in their own directories in the Hasura project. Metadata is managed in its separate metadata directory and PG schema migrations are managed via migration files that are now in SQL format.

Changes needed in existing workflows

Due to the above mentioned changes, any workflows that involve applying migrations have an additional step of applying metadata as well.

For example,

  • any place where the hasura migrate apply command is used, it now needs to be followed by a hasura metadata apply command.
  • if the cli-migrations Docker image is used for auto applying migrations at server start, now you will have to use the cli-migrations-v2 image and the /metadata directory will also have to be mounted along with the /migrations directory

Upgrade steps

Step 0: Take a backup

Make sure you take a backup of your Hasura project before upgrading to config v2.

Step 1: Upgrade to the latest CLI

Config v2 is available since v1.2.0.


hasura update-cli

Step 2: Upgrade hasura project to v2

In your project directory, run:

hasura scripts update-project-v2

Your project directory and config.yaml should be updated to v2.