Managing Hasura metadata

Introduction

If your Postgres schema is already managed with a tool like knex, TypeORM, Django/Rails migrations, you will still need a way to export the actions you performed on the Hasura console to apply it later on another Hasura instance.

All the actions performed on the console, like tracking tables/views/functions, creating relationships, configuring permissions, creating event triggers and remote schemas, etc. can be exported as a JSON/yaml metadata file which can be version controlled. The metadata file can be later imported to another Hasura instance to get the same configuration. You can also manually edit the metadata file to add more objects to it and then use it to update the instance.

Exporting Hasura metadata

CLI
Console
API

Metadata can be exported with the hasura metadata export command.

This will export the metadata as yaml files in the /metadata directory

  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.

    Export metadata

  3. This will prompt a file download for hasura_metadata_<timestamp>.json. Save the file.

The export can be done via the export_metadata metadata API. Response will be a JSON object with the Hasura metadata.

Here is an example using curl to save this as a file:

curl -d'{"type": "export_metadata", "args": {}}' http://localhost:8080/v1/metadata -o hasura_metadata.json

This command will create a hasura_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.

Note

The metadata exported via the console and API will be a single JSON file that can be applied via the console or the API only.

The metadata exported via the CLI is broken into multiple YAML files for easier management in version control and CI/CD and can be applied via the CLI or the cli-migrations image only.

Applying/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, i.e. you lose any metadata that was already present before.

CLI
Console
API
Metadata can be applied with the hasura metadata apply command.

  1. Click on the settings (⚙) icon at the top right corner of the console screen.

  2. Click on Import Metadata button.

    Import metadata

  3. Choose a hasura_metadata.json file that was exported earlier.

  4. A notification should appear indicating the success or error.

The exported JSON can be imported via the replace_metadata metadata API.

Here is an example using curl:

curl -d'{"type":"replace_metadata", "args":'$(cat hasura_metadata.json)'}' http://localhost:8080/v1/metadata

This command reads the hasura_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

All the dependent objects, like tables, views, functions etc. should exist on Postgres before importing the metadata. Otherwise, it will result in an error saying the object does not exist. So, apply the Postgres schema first, before importing the metadata.

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.

CLI
Console
API
Metadata can be reloaded with the hasura metadata reload command.

  1. Click on the settings (⚙) icon at the top right corner of the console screen.

  2. Click on Reload button.

    Reload metadata

  3. A notification should appear indicating the success.

The reload of metadata can be done via the reload_metadata metadata API.

Here is an example using curl:

curl -d'{"type": "reload_metadata", "args": {}}' http://localhost:8080/v1/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

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.

Resetting Hasura metadata

Resetting GraphQL engine’s metadata is an irreversible process. It is recommended to first export the metadata so that it can be reapplied if needed or else that information will be lost and Hasura will have to be configured again from scratch (e.g. tracking tables, relationships, creating triggers, actions, etc.).

CLI
Console
API
Metadata can be reset with the hasura metadata clear command.

  1. Click on the settings (⚙) icon at the top right corner of the console screen.

  2. Click on Reset button.

    Reset metadata

  3. A pop-up will appear prompting you to confirm the process.

  4. A notification should appear indicating the success.

The reset of metadata can be done via the clear_metadata metadata API.

Here is an example using curl:

curl -d'{"type": "clear_metadata", "args": {}}' http://localhost:8080/v1/metadata

If an admin secret is set, add -H 'X-Hasura-Admin-Secret: <your-admin-secret>' as the API is an admin-only API.

Managing Hasura metadata in CI/CD

In case you need an automated way of applying/importing the metadata, take a look at the cli-migrations Docker image, which can start the GraphQL engine after automatically importing a mounted metadata directory.

« previous | next »
Want to contribute or report missing content?

Powered by Sphinx. | Copyright © 2021 Hasura.