docs: add a guide to clear hasura migrations (close #5372)

### Description
This PR adds information on clearing migrations to the docs.

### Changelog
- [x] `CHANGELOG.md` is updated with user-facing content relevant to this PR. If no changelog is required, then add the `no-changelog-required` label.

### Affected components
- [x] Docs

### Related Issues
https://github.com/hasura/graphql-engine/issues/5372

### Old PR
https://github.com/hasura/graphql-engine-mono/pull/224

### Affected pages
https://deploy-preview-273--hasura-docs-mono.netlify.app/graphql/core/migrations/advanced/resetting-migrations.html

Co-authored-by: Rikin Kachhia <54616969+rikinsk@users.noreply.github.com>
GitOrigin-RevId: 7ccf3fc172ef4bb48f0fef2acd2126992b6447eb
This commit is contained in:
Funmilayo E. Olaiya 2021-02-17 15:15:09 +01:00 committed by hasura-bot
parent cb029c317b
commit 3d077bdc97
2 changed files with 81 additions and 0 deletions

View File

@ -14,5 +14,6 @@ Migrations advanced use cases
writing-migrations-manually
rolling-back-migrations
seed-data-migration
resetting-migrations
.. collaboration

View File

@ -0,0 +1,80 @@
.. meta::
:description: Resetting Hasura migrations
:keywords: hasura, docs, migration, reset migrations, clear migrations
.. _reset_migration:
Resetting Hasura migrations
===========================
.. contents:: Table of contents
:backlinks: none
:depth: 1
:local:
Introduction
------------
This page explains how to reset the state of migrations and create new migrations from the state that is on the server.
This can be useful if the current migration state on your local machine is corrupted.
Step 1: Delete the local migration files
----------------------------------------
Move all your migrations to a backup folder, in case you may need them later.
You can use the following command:
.. code-block:: bash
# move the contents of the migrations folder into the migrations_backup folder
mv migrations migrations_backup
Step 2: Reset the migration history on the server
-------------------------------------------------
On the SQL tab of the Hasura console, run the following command:
.. code-block:: bash
TRUNCATE hdb_catalog.schema_migrations;
Step 3: Pull the schema and metadata from the server
----------------------------------------------------
If the migrations were reset, then we will set up fresh migrations by pulling the schema and metadata from the server using the following commands:
.. code-block:: bash
## create migration files - "this will only export public schema from postgres"
hasura migrate create "init" --from-server
.. code-block:: bash
## note down the version
## mark the migration as applied on this server
hasura migrate apply --version "<version>" --skip-execution
.. code-block:: bash
## to also export the Hasura metadata and save it in the ``/metadata`` directory
hasura metadata export
.. note::
If you are using schemas other than ``public``, use the ``--schema <schema_name>`` flag to indicate each one of them in the create command. This flag can be used multiple times.
Step 4: Verify the status of the migrations
-------------------------------------------
Run the following command to verify the migration status:
.. code-block:: bash
hasura migrate status
You should see the new migrations!