Downgrading Hasura GraphQL engine¶

Step 1: Update Hasura GraphQL engine image version¶

The Hasura GraphQL engine runs off a Docker image and downgrades are as simple as changing the image tag to the version you want.

Based on your deployment method, follow the appropriate guide to downgrade the GraphQL engine version you’re running:

• Updating on Heroku
• Updating on Docker
• Updating on Kubernetes

If the GraphQL engine version you are downgrading to has a different catalogue version than your current, you will have to downgrade the catalogue to the corresponding version manually as described below.

Step 2: Downgrade Hasura catalogue version¶

The Hasura GraphQL engine maintains its metadata state in a “catalogue” as described here. The schema of the catalogue is versioned. Updates to the Hasura GraphQL engine may have Hasura catalogue version bumps.

Downgrades to the catalogue need to be carried out manually in case you are attempting to downgrade to a lower Hasura GraphQL engine version.

From v1.2.0, you can downgrade the catalogue from a particular version to a previous version by executing the graphql-engine executable on the command line, with the downgrade command, specifying the desired catalogue version using one of the --to- flags. For earlier versions, it is recommended to first upgrade to the latest version and then use the downgrade command to downgrade to the desired version.

The downgrade command is not part of the Hasura CLI but rather a command on graphql-engine itself. The way to execute this command is to run:

docker run -e HASURA_GRAPHQL_DATABASE_URL=$DATABASE_URL hasura/graphql-engine:<VERSION> graphql-engine downgrade --to-<NEW-VERSION>

You need to use a newer version of graphql-engine to downgrade to an older version, since only the newer version knows how to downgrade from that point in time. After you’ve executed the downgrade command using the newer version, you should switch to the older version and run graphql-engine serve as normal.

Catalogue version downgrades will be executed sequentially and in a single transaction.