Updating Hasura Cloud v1.3 Projects to Hasura v2.0

Available on: Cloud Free, Cloud Professional, Cloud Enterprise

Introduction

Hasura Cloud now creates new projects with Hasura v2.0 by default. Due to some behavior and underlying architectural changes in v2.0, existing projects have not been auto-updated to v2.0. You can update your older v1.3 projects to v2.0 by following this guide.

(You can find the older guide to do this process manually here)

Note

In case you happen to have a large number of past cron and Event Trigger logs in your database, this might slow down the update to v2 and might even cause DB errors in certain scenarios.

It is highly recommended to clean up past cron and Event Trigger logs data from the database before attempting the update if you have a lot of historical data.

You can take a dump of this data before cleaning up if you wish to keep the log history.

What has changed?

Check the core updating to v2.0 guide and the release notes to see what new concepts, features and behavior changes have been introduced in Hasura v2.0.

Note that Hasura v2 Cloud projects' Metadata is now stored in Metadata DBs managed by Hasura Cloud. Hence the new HASURA_GRAPHQL_METADATA_DATABASE_URL env var is not configurable on Hasura Cloud and is managed by Hasura Cloud itself.

See the section on hasura_v1_v2_compatibility to use a Hasura v2 Cloud project like a Hasura v1 Cloud project.

Estimated time needed for update

Depending on the size of your project the update process should typically take around 5-10 minutes to be completed.

Project availability during update

During the update process Hasura Cloud will need to place your project in a "Maintenance mode" till the process is complete.

When Cloud maintenance mode is enabled, all Hasura Cloud project actions such as updating env vars, transferring ownership, etc. will be disabled.

When Server maintenance mode is enabled, all actions updating the project Metadata such as tracking tables, adding relationships, etc. will be disabled.

Hence it is recommended to update your project at a time convenient to all project collaborators.

Apart from the brief moments needed to enable/disable the server maintenance mode, your GraphQL API will continue to function during this period.

Post-update steps

• As with most major updates, we would recommend you to monitor and ensure all functionalities of your project are working as expected post the update and the update did not cause any unexpected changes. Do get in touch with us in case you notice anything unexpected.
• You can choose to unset the HASURA_GRAPHQL_V1_BOOLEAN_NULL_COLLAPSE env var that was added to your project during the update to preserve a v1.3 behavior that was modified in v2.0. See details. We recommend moving to the new behavior by unsetting the env var after verifying your project is not impacted by the change.
• Check the Post update steps section of the core updating to v2.0 guide for other changes you should make post your project update.

Update process

Update option might not be currently enabled for all users

If you do not see the option to update your project as mentioned below, please reach out to support.

To start the update, you should see a button called Update next to your project on the Project list page as shown below:

Clicking on this button will trigger an update job that will perform a few tasks to update your current v1.3 project to v2.0.

Refer to the following task wise breakdown of the update job to understand what the job will be doing and to check your project end state in case of any failures.

Do reach out to support if you observe any issues with the update process or run into any other problems post the v2.0 update.

Update job sub-tasks

The following is a task wise breakdown of the update to v2.0 job.

Each task in the update job has a rollback strategy in case any failures occur. If the rollback steps of any task fail, the project might be in an unhealthy state in which case please get in touch with support immediately for assistance.

Step 1: Initializing

Step 1.1: Validating

Sub-tasks:

• Enable cloud maintenance mode
• Ensure infrastructure for update is available

On Failure:

• Disable cloud maintenance mode
• Project stays in v1.3

Step 1.2: Enabling maintenance mode

Sub-tasks:

• Set HASURA_GRAPHQL_ENABLE_MAINTENANCE_MODE env var to enable server maintenance mode
• Set HASURA_GRAPHQL_V1_BOOLEAN_NULL_COLLAPSE env var to true to maintain v1.3 behavior for null values in where filters. (Know more)

On Failure:

• Unset HASURA_GRAPHQL_V1_BOOLEAN_NULL_COLLAPSE env var
• Unset HASURA_GRAPHQL_ENABLE_MAINTENANCE_MODE env var to disable server maintenance mode
• Disable cloud maintenance mode
• Project stays in v1.3

Step 2: Updating project

Step 2.1: Migrating project metadata

Sub-tasks:

• Take a backup of server Metadata from user database & move Metadata to cloud Metadata database

On Failure:

• Unset HASURA_GRAPHQL_V1_BOOLEAN_NULL_COLLAPSE env var
• Unset HASURA_GRAPHQL_ENABLE_MAINTENANCE_MODE env var to disable server maintenance mode
• Disable cloud maintenance mode
• Project stays in v1.3

Step 2.2: Creating v2.0 instance

Sub-tasks:

• Create v2.0 instance
• Start routing requests to v2.0 instance

On Failure:

• Start routing requests back to v1.3 instance
• Unset HASURA_GRAPHQL_ENABLE_MAINTENANCE_MODE env var to disable server maintenance mode
• Disable cloud maintenance mode
• Project stays in v1.3

Step 2.3: Migrating pending events, async actions data

Sub-tasks:

• Send signal to shutdown v1.3 instance
• Wait for v1.3 to gracefully shutdown after completing processing of any in-flight events
• Migrate pending events, async actions data to cloud Metadata database

On Failure:

• Restart v1.3 instance
• Start routing requests back to v1.3 instance
• Unset HASURA_GRAPHQL_ENABLE_MAINTENANCE_MODE env var to disable server maintenance mode
• Disable cloud maintenance mode
• Project stays in v1.3

Step 2.4: Migrating processed events, async actions data

Sub-tasks:

• Migrate invocation logs of processed events, async actions to cloud Metadata database

On Failure:

• No action taken. Job continues to next task
• Invocation logs of already processed events, async actions are not migrated. Contact support to assist with a manual migration of the logs if needed

Step 3: Validating update

Step 3.1: Disabling maintenance mode

Sub-tasks:

• Unset HASURA_GRAPHQL_ENABLE_MAINTENANCE_MODE env var to disable server maintenance mode
• Disable cloud maintenance mode

On Failure:

• No action taken. Job continues to next task
• Server maintenance mode can be disabled manually by setting HASURA_GRAPHQL_ENABLE_MAINTENANCE_MODE env var to false
• Contact support if your project is in an unexpected state

Step 3.2: Check Metadata consistency

Sub-tasks:

• Check if Metadata is consistent

On Failure:

• No action taken. Job continues to next task
• Check your project Metadata status on the Console (Settings (⚙) -> Metadata status) and attempt reloading metadata if there is an unexpected inconsistency reported. Contact support if the inconsistency doesn't go away on metadata reload.

4. Project update complete

Project update to v2.0 is completed.