mirror of
https://github.com/hasura/graphql-engine.git
synced 2024-12-21 14:31:55 +03:00
152 lines
4.4 KiB
ReStructuredText
152 lines
4.4 KiB
ReStructuredText
.. meta::
|
|
:description: Hasura migrations basics
|
|
:keywords: hasura, docs, migration, metadata
|
|
|
|
.. _migrations_basics:
|
|
|
|
Hasura migrations basics
|
|
========================
|
|
|
|
.. contents:: Table of contents
|
|
:backlinks: none
|
|
:depth: 1
|
|
:local:
|
|
|
|
.. note::
|
|
|
|
For ``config v1``, see :ref:`manage_migrations_v1`.
|
|
|
|
Initializing migrations
|
|
-----------------------
|
|
|
|
:ref:`Install <install_hasura_cli>` the Hasura CLI or :ref:`update <hasura_update-cli>`
|
|
to the latest version if current version is ``< v1.2.0``.
|
|
|
|
Now run:
|
|
|
|
.. code-block:: bash
|
|
|
|
# create a Hasura project
|
|
hasura init
|
|
|
|
# cd into project dir
|
|
|
|
# Export current Hasura state
|
|
hasura migrate create <init-migration-name> --from-server --endpoint <endpoint>
|
|
hasura metadata export --endpoint <endpoint>
|
|
|
|
# mark the init migration as applied on this server
|
|
hasura migrate apply --version "<init-migration-version>" --skip-execution
|
|
|
|
Generating migrations
|
|
---------------------
|
|
|
|
.. rst-class:: api_tabs
|
|
.. tabs::
|
|
|
|
.. tab:: Via console
|
|
|
|
- Open the Hasura console via the CLI
|
|
|
|
.. code-block:: bash
|
|
|
|
hasura console
|
|
|
|
- As you make changes, migration files will be created and latest
|
|
metadata will be exported automatically
|
|
|
|
.. tab:: Manually
|
|
|
|
- Create a new migration
|
|
|
|
.. code-block:: bash
|
|
|
|
hasura migrate create <name-of-migration>
|
|
|
|
- Add SQL manually to the ``up.sql`` and ``down.sql`` files in the newly
|
|
created migration's directory in ``/migrations``
|
|
- Edit the corresponding metadata manually in ``/metadata``
|
|
|
|
Managing migrations
|
|
-------------------
|
|
|
|
For maintaining a clean set of migrations with the possibility to move between
|
|
different checkpoints in your project's state it is recommended to clean
|
|
up intermediate DB migration files and to version control the Hasura project.
|
|
|
|
Squash migrations
|
|
^^^^^^^^^^^^^^^^^
|
|
|
|
Typically while adding a feature a lot of incremental migration files get
|
|
created for each of the small tasks that you did to achieve the feature.
|
|
|
|
Once you are confident about the final state of a feature, you can use the
|
|
``migrate squash`` command to make a single DB migration file containing all
|
|
the intermediate steps required to reach the final state.
|
|
|
|
.. code-block:: bash
|
|
|
|
hasura migrate squash --name "<feature-name>" --from <migration-version>
|
|
|
|
# mark the squashed migration as applied on this server
|
|
hasura migrate apply --version "<squash-migration-version>" --skip-execution
|
|
|
|
Add checkpoints
|
|
^^^^^^^^^^^^^^^
|
|
|
|
As your metadata is exported on every change you make to the schema, once a final
|
|
state for a feature is reached you should mark it as a checkpoint via version
|
|
control so that you can get back the metadata at that point.
|
|
|
|
.. code-block:: bash
|
|
|
|
git commit -m "<feature-name>"
|
|
|
|
Applying migrations
|
|
-------------------
|
|
|
|
- Get the Hasura project with the ``migrations`` and ``metadata`` directories.
|
|
|
|
- Apply DB migration files and metadata snapshot
|
|
|
|
.. code-block:: bash
|
|
|
|
hasura migrate apply --endpoint <server-endpoint>
|
|
hasura metadata apply --endpoint <server-endpoint>
|
|
|
|
Your Hasura server should be up and running!
|
|
|
|
Checking migrations status
|
|
--------------------------
|
|
|
|
The following command will print out each migration version present in the ``migrations``
|
|
directory along with its name, source status and database status.
|
|
|
|
.. code-block:: bash
|
|
|
|
# in project dir
|
|
hasura migrate status
|
|
|
|
For example,
|
|
|
|
.. code-block:: bash
|
|
|
|
$ hasura migrate status
|
|
VERSION NAME SOURCE STATUS DATABASE STATUS
|
|
1590493510167 init Present Present
|
|
1590497881360 create_table_public_address Present Present
|
|
|
|
Such a migration status indicates that there are 2 migration versions in the
|
|
local directory and both of them are applied on the database.
|
|
|
|
If ``SOURCE STATUS`` indicates ``Not Present``, it means that the migration
|
|
version is present on the server, but not on the current user's local directory.
|
|
This typically happens if multiple people are collaborating on a project and one
|
|
of the collaborators forgot to pull the latest changes which included the latest
|
|
migration files, or another collaborator forgot to push the latest migration
|
|
files that were applied on the database. Syncing of the files would fix the
|
|
issue.
|
|
|
|
If ``DATABASE STATUS`` indicates ``Not Present``, it denotes that there are new
|
|
migration versions in the local directory which are not applied on the database
|
|
yet. Executing ``hasura migrate apply`` will resolve this. |