add reload metadata instructions in docs (close #2004) (#3264)

This commit is contained in:
ap 2019-11-12 14:09:00 +01:00 committed by Rikin Kachhia
parent 689c97e9a1
commit f36587a7de
2 changed files with 57 additions and 15 deletions

View File

@ -30,21 +30,21 @@ Exporting Hasura metadata
1. Click on the settings (⚙) icon at the top right corner of the console screen.
2. In the Hasura metadata actions page that opens, click on the ``Export Metadata`` button.
3. This will prompt a file download for ``metadata.json``. Save the file.
3. This will prompt a file download for ``metadata.json``. Save the file.
.. tab:: API
The export can be done via the :doc:`Metadata API
<../api-reference/schema-metadata-api/manage-metadata>` too.
Response will be a JSON object with the Hasura metadata. Here is a example
<../api-reference/schema-metadata-api/manage-metadata>`.
Response will be a JSON object with the Hasura metadata. Here is an example
using ``curl`` to save this as a file:
.. code-block:: bash
curl -d'{"type": "export_metadata", "args": {}}' http://localhost:8080/v1/query -o metadata.json
This command will create a ``metadata.json`` file. If admin secret is set,
add ``-H 'X-Hasura-Admin-Secret: <your-admin-secret>'`` as the API is an
This command will create a ``metadata.json`` file.
If an admin secret is set, add ``-H 'X-Hasura-Admin-Secret: <your-admin-secret>'`` as the API is an
admin-only API.
Importing Hasura metadata
@ -53,7 +53,8 @@ Importing Hasura metadata
You can apply exported metadata from one Hasura GraphQL engine instance to another. You can also apply an older or
modified version of an instance's metadata onto itself.
Importing completely replaces the metadata on that instance. ie: you lose any metadata that was already present
Importing completely replaces the metadata on that instance, i.e. you lose any metadata that was already present
before.
.. rst-class:: api_tabs
.. tabs::
@ -68,17 +69,17 @@ Importing completely replaces the metadata on that instance. ie: you lose any me
.. tab:: API
The exported JSON can be imported via the :doc:`Metadata API
<../api-reference/schema-metadata-api/manage-metadata>` too.
Here is a example using ``curl``:
<../api-reference/schema-metadata-api/manage-metadata>`.
Here is an example using ``curl``:
.. code-block:: bash
curl -d'{"type":"replace_metadata", "args":'$(cat metadata.json)'}' http://localhost:8080/v1/query
This command will read the ``metadata.json`` file and makes a POST request to
replace the metadata. If an admin secret is set, add ``-H
'X-Hasura-Admin-Secret: <your-admin-secret>'`` as the API is an admin-only
API.
This command reads the ``metadata.json`` file and makes a POST request to
replace the metadata.
If an admin secret is set, add ``-H 'X-Hasura-Admin-Secret: <your-admin-secret>'`` as the API is an
admin-only API.
.. note::
@ -88,7 +89,48 @@ Importing completely replaces the metadata on that instance. ie: you lose any me
importing the metadata.
The ``curl`` based API calls can be easily integrated with your CI/CD workflows.
.. _reload_metadata_manual:
Reloading Hasura metadata
-------------------------
In some cases, the metadata can be out of sync with the Postgres schema. For example,
when a new column has been added to a table via an external tool such as ``psql``.
.. rst-class:: api_tabs
.. tabs::
.. tab:: Console
1. Click on the settings (⚙) icon at the top right corner of the console screen.
2. Click on ``Reload`` button.
3. A notification should appear indicating the success.
.. tab:: API
The reload of metadata can be done via the :doc:`Metadata API
<../api-reference/schema-metadata-api/manage-metadata>`.
Here is an example using ``curl``:
.. code-block:: bash
curl -d'{"type": "reload_metadata", "args": {}}' http://localhost:8080/v1/query
If an admin secret is set, add ``-H 'X-Hasura-Admin-Secret: <your-admin-secret>'`` as the API is an
admin-only API.
.. note::
Reloading may result in inconsistent metadata status. You may need to resolve
all inconsistent objects manually or delete them. After that, you need to reload
metadata again.
Managing Hasura metadata in CI/CD
---------------------------------
Using tools like ``curl`` you can easily integrate the metadata API requests for the above metadata management
actions with your CI/CD workflows.
In case you need an automated way of applying/importing the metadata, take a
look at the :doc:`CLI-Migrations <auto-apply-migrations>` Docker image, which
can start the GraphQL engine after automatically importing a mounted metadata file.
can start the GraphQL engine after automatically importing a mounted metadata file.

View File

@ -239,4 +239,4 @@ Current limitations
^^^^^^^^^^^^^^^^^^^
Currently, Hasura does not automatically detect changes to the contents of enum tables, so the GraphQL schema will
only be updated after manually reloading metadata after inserting, updating, or deleting rows from an enum table.
only be updated after :ref:`manually reloading metadata <reload_metadata_manual>` after inserting, updating, or deleting rows from an enum table.