mirror of
https://github.com/hasura/graphql-engine.git
synced 2024-09-11 10:46:25 +03:00
docs: add cloud v2 update guide
Co-authored-by: github-actions[bot] <41898282+github-actions[bot]@users.noreply.github.com> GitOrigin-RevId: 581f08d36caf95d653fe88ee050b11f657614da4
This commit is contained in:
Rikin Kachhia
hasura-bot
parent
2d8ac777b3
commit
90f9806c99
@ -63,5 +63,5 @@ Dig deeper
|
||||
Heroku database URL Sync <heroku-url-sync>
|
||||
Maintenance mode <maintenance-mode>
|
||||
Deleting projects <delete>
|
||||
Moving v1.3 projects to v2.0 <move-project-v2>
|
||||
Updating v1.3 projects to v2.0 <move-project-v2>
|
||||
|
||||
|
||||
@ -21,7 +21,7 @@ for your project.
|
||||
|
||||
.. note::
|
||||
|
||||
Currently, maintenance mode will only be activated for your project while you
|
||||
Currently, cloud maintenance mode will only be activated for your project while you
|
||||
are updating it to Hasura GraphQL Engine ``v2.0``.
|
||||
|
||||
.. note::
|
||||
|
||||
69
docs/graphql/cloud/projects/move-project-v2-manual.rst
Normal file
69
docs/graphql/cloud/projects/move-project-v2-manual.rst
Normal file
@ -0,0 +1,69 @@
|
||||
.. meta::
|
||||
:description: Moving project to v2
|
||||
:keywords: hasura, docs, project, upgrade, move, v2
|
||||
|
||||
.. _move_project_v2:
|
||||
|
||||
Manually moving Hasura Cloud v1.3 projects to Hasura v2.0
|
||||
=========================================================
|
||||
|
||||
.. contents:: Table of contents
|
||||
:backlinks: none
|
||||
:depth: 2
|
||||
:local:
|
||||
|
||||
Introduction
|
||||
------------
|
||||
|
||||
Hasura Cloud now creates new projects with Hasura ``v2.0`` by default. Due to
|
||||
some underlying architectural changes in ``v2.0``, existing projects have not
|
||||
yet been upgraded to ``v2.0``.
|
||||
|
||||
In the meanwhile it is possible to manually "move" your project to use Hasura
|
||||
``v2.0``. You will lose any scheduled events and the history of your processed events
|
||||
and async actions in the process though.
|
||||
|
||||
Do check the `changelog <https://github.com/hasura/graphql-engine/releases>`__ first
|
||||
to see what changes and features have been introduced.
|
||||
|
||||
Move existing v1.3 project to a v2.0 project
|
||||
--------------------------------------------
|
||||
|
||||
As it is not possible to actually upgrade your ``v1.3`` project to ``v2.0``, you will have to
|
||||
essentially create a new Hasura project with ``v2.0`` and connect it with your database with the same
|
||||
Hasura metadata as in the previous project.
|
||||
|
||||
Step 1: Export metadata from existing project
|
||||
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
|
||||
|
||||
See :ref:`exporting metadata <exporting_metadata>` to get a copy of the current Hasura metadata
|
||||
on your project.
|
||||
|
||||
Do ensure no further changes are made to the Hasura metadata post this.
|
||||
|
||||
Step 2: Create a v2.0 Cloud project
|
||||
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
|
||||
|
||||
See ``Step 1`` of :ref:`creating projects <create_project>` to create a new Hasura Cloud ``v2.0``
|
||||
project.
|
||||
|
||||
Step 3: Connect your database with the name **default** to the new project
|
||||
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
|
||||
|
||||
See ``Step 2`` of :ref:`creating projects <create_project>` to connect your existing database to
|
||||
the new project. Please ensure you set the database name as ``default``.
|
||||
|
||||
.. note::
|
||||
|
||||
After connecting a database to a ``v2.0`` project it will not be usable with
|
||||
a ``v1.3`` project. Hence it is recommended to stop your ``v1.3`` project
|
||||
before doing this.
|
||||
|
||||
Step 4: Apply the exported metadata to the new project
|
||||
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
|
||||
|
||||
See :ref:`applying metadata <applying_metadata>` to apply the earlier exported metadata to the new
|
||||
project.
|
||||
|
||||
Your GraphQL API should now be regenerated as in the earlier ``v1.3`` project.
|
||||
|
||||
@ -1,11 +1,11 @@
|
||||
.. meta::
|
||||
:description: Moving project to v2
|
||||
:keywords: hasura, docs, project, upgrade, move, v2
|
||||
:description: Updating v1 Cloud project to v2
|
||||
:keywords: hasura, docs, project, upgrade, update, v2
|
||||
|
||||
.. _move_project_v2:
|
||||
.. _update_project_v2:
|
||||
|
||||
Manually moving Hasura Cloud v1.3 projects to Hasura v2.0
|
||||
=========================================================
|
||||
Updating Hasura Cloud v1.3 projects to Hasura v2.0
|
||||
==================================================
|
||||
|
||||
.. contents:: Table of contents
|
||||
:backlinks: none
|
||||
@ -16,54 +16,244 @@ Introduction
|
||||
------------
|
||||
|
||||
Hasura Cloud now creates new projects with Hasura ``v2.0`` by default. Due to
|
||||
some underlying architectural changes in ``v2.0``, existing projects have not
|
||||
yet been upgraded to ``v2.0``. **This upgrade will be done automatically in the
|
||||
very near future.**
|
||||
some behaviour 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.
|
||||
|
||||
In the meanwhile it is possible to manually "move" your project to use Hasura
|
||||
``v2.0``.
|
||||
(*You can find the older guide to do this process manually* :ref:`here <move_project_v2>`)
|
||||
|
||||
Do check the `changelog <https://github.com/hasura/graphql-engine/releases>`__ first
|
||||
to see what changes and features have been introduced.
|
||||
Pre-update steps
|
||||
----------------
|
||||
|
||||
Move existing v1.3 project to a v2.0 project
|
||||
--------------------------------------------
|
||||
Check the :ref:`core updating to v2.0 <upgrade_hasura_v2>` guide and the
|
||||
`release notes <https://github.com/hasura/graphql-engine/releases>`__ to see what new concepts,
|
||||
features and behaviour changes have been introduced in Hasura ``v2.0``.
|
||||
|
||||
As it is not possible to actually upgrade your ``v1.3`` project to ``v2.0``, you will have to
|
||||
essentially create a new Hasura project with ``v2.0`` and connect it with your database with the same
|
||||
Hasura metadata as in the previous project.
|
||||
Estimated time needed for update
|
||||
--------------------------------
|
||||
|
||||
Step 1: Export metadata from existing project
|
||||
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
|
||||
Depending on the size of your project the update process should typically take around **5-10 minutes** to be completed.
|
||||
|
||||
See :ref:`exporting metadata <exporting_metadata>` to get a copy of the current Hasura metadata
|
||||
on your project.
|
||||
Project availability during update
|
||||
----------------------------------
|
||||
|
||||
Do ensure no further changes are made to the Hasura metadata post this.
|
||||
During the update process Hasura Cloud will need to place your project in a "Maintenance mode" till the process is complete.
|
||||
|
||||
Step 2: Create a v2.0 Cloud project
|
||||
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
|
||||
When **Cloud maintenance mode** is enabled, all Hasura Cloud actions such as updating env vars, transferring ownership, etc. will be disabled.
|
||||
|
||||
See ``Step 1`` of :ref:`creating projects <create_project>` to create a new Hasura Cloud ``v2.0``
|
||||
project.
|
||||
When **Server maintenance mode** is enabled, all actions updating the project metadata such as tracking tables, adding relationships, etc.
|
||||
will be disabled.
|
||||
|
||||
Step 3: Connect your database with the name **default** to the new project
|
||||
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
|
||||
Hence it is recommended to update your project at a time convenient to all project collaborators.
|
||||
|
||||
See ``Step 2`` of :ref:`creating projects <create_project>` to connect your existing database to
|
||||
the new project. Please ensure you set the database name as ``default``.
|
||||
Apart from the brief moments needed to enable/disable the server maintenance mode, **your GraphQL API will continue to function during this period.**
|
||||
|
||||
.. note::
|
||||
Post-update steps
|
||||
-----------------
|
||||
|
||||
After connecting a database to a ``v2.0`` project it will not be usable with
|
||||
a ``v1.3`` project. Hence it is recommended to stop your ``v1.3`` project
|
||||
before doing this.
|
||||
- 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.
|
||||
|
||||
Step 4: Apply the exported metadata to the new project
|
||||
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
|
||||
- You can choose to remove the following env vars that were added to your project during the update
|
||||
to preserve some ``v1.3`` behaviours that were modified in ``v2.0``. We recommend moving to the new behaviour
|
||||
if your project is not impacted by the changes.
|
||||
|
||||
See :ref:`applying metadata <applying_metadata>` to apply the earlier exported metadata to the new
|
||||
project.
|
||||
- ``HASURA_GRAPHQL_V1_BOOLEAN_NULL_COLLAPSE``
|
||||
|
||||
Your GraphQL API should now be regenerated as in the earlier ``v1.3`` project.
|
||||
Check the :ref:`Behaviour changes <hasura_v2_behaviour_changes>` section of the core updating to v2.0 guide
|
||||
for details regarding the behaviour changes.
|
||||
|
||||
- Check the :ref:`Post update steps <hasura_v1_to_v2_post_update_steps>` section of the core updating to v2.0 guide
|
||||
for other changes you might wish to make post your project update.
|
||||
|
||||
Update process
|
||||
--------------
|
||||
|
||||
.. admonition:: Update option might not be currently enabled for all users
|
||||
|
||||
If you do not see the option to update your project as mentioned below yet, you can expect to see so
|
||||
in the coming few days.
|
||||
|
||||
To start the update, you should see a button called ``Update`` next to your project on the Project list page
|
||||
as shown below:
|
||||
|
||||
.. thumbnail:: /img/graphql/cloud/projects/update-project.png
|
||||
:width: 700px
|
||||
:alt: Update project
|
||||
|
||||
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.
|
||||
|
||||
.. contents::
|
||||
:backlinks: none
|
||||
:depth: 2
|
||||
:local:
|
||||
|
||||
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`` behaviour for ``null`` values in ``where`` filters. :ref:`(Know more) <hasura_v2_behaviour_changes>`
|
||||
|
||||
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**
|
||||
|
||||
.. _v2_update_migrate_invocation_logs:
|
||||
|
||||
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
|
||||
"""""""""""""""""""""""""
|
||||
|
||||
.. _v2_update_disable_maintenance_mode:
|
||||
|
||||
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
|
||||
|
||||
.. _v2_update_check_consistency:
|
||||
|
||||
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.
|
||||
|
||||
@ -9,7 +9,7 @@ API Reference
|
||||
|
||||
.. contents:: Table of contents
|
||||
:backlinks: none
|
||||
:depth: 1
|
||||
:depth: 2
|
||||
:local:
|
||||
|
||||
Available APIs
|
||||
|
||||
@ -312,6 +312,12 @@ For the ``serve`` sub-command these are the available flags and ENV variables:
|
||||
|
||||
*(Available for versions > v2.0.0)*
|
||||
|
||||
* - ``--enable-maintenance-mode``
|
||||
- ``HASURA_GRAPHQL_ENABLE_MAINTENANCE_MODE``
|
||||
- Disable updating of metadata on the server (default: ``false``)
|
||||
|
||||
*(Available for versions > v2.0.0)*
|
||||
|
||||
.. note::
|
||||
|
||||
When the equivalent flags for environment variables are used, the flags will take precedence.
|
||||
|
||||
@ -27,7 +27,7 @@ Guides / Tutorials / Resources
|
||||
Telemetry <telemetry>
|
||||
Code Editor Integrations <code-editor-integrations/index>
|
||||
MySQL preview <mysql-preview>
|
||||
Upgrading to Hasura v2 <upgrade-hasura-v2>
|
||||
Updating to Hasura v2 <upgrade-hasura-v2>
|
||||
|
||||
.. note::
|
||||
|
||||
|
||||
@ -191,6 +191,11 @@ and restarting your Hasura instance should work seamlessly. The database connect
|
||||
env var will be added as a database with the name ``default`` automatically and all existing metadata and migrations will be
|
||||
assumed to belong to it.
|
||||
|
||||
.. _hasura_v1_to_v2_post_update_steps:
|
||||
|
||||
Post update steps
|
||||
-----------------
|
||||
|
||||
Upgrade CLI project to enable multiple database support
|
||||
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
|
||||
|
||||
|
||||
BIN
docs/img/graphql/cloud/projects/update-project.png
Normal file
BIN
docs/img/graphql/cloud/projects/update-project.png
Normal file
Binary file not shown.
|
After Width: | Height: | Size: 17 KiB |
Loading…
Reference in New Issue
Block a user