Metadata Best Practices

Introduction

Proper Metadata management ensures the Hasura GraphQL Engine operates appropriately and as expected. You can use several different patterns to manage Metadata successfully. However, the below do's, and don'ts have been gathered through real-world practices, user experiences, and challenges when managing enterprise-scale Hasura ecosystems.

Recommended patterns

• Always use custom environment variables instead of hardcoded values whenever possible. These environment variables can then be reused in the other environments (e.g., staging or production) while containing a reference to the environment-specific values. This is necessary for a seamless CI/CD implementation.

  For example, the metadata contains a reference to my_database_conn_string but the environment variable for the development environment refers to the development database while the production environment refers to the production database. Hasura will appropriately substitute these values when using the connection strings.

  • The environment variable can be any plain-text value, such as my_remote_schema_url, but should not start HASURA_... in order to easily identify the environment variable as used natively by Hasura or created by the user.

  • The Console allows for configuration of many things, such as data sources, by specifying connection via environment variable. Select this option and enter the environment variable you declared in your deployment.

  • Some features, such as Remote Schemas, do not explicitly have a configuration for this in the Console. In these situations, templatize the environment variable by wrapping it in double curly brackets. e.g. {{my_remote_schema_url}}

• Use the Hasura CLI to manage and export Metadata.

  • The CLI exports YAML files which is much more source-control friendly than JSON (exported by the Console and API).
  • Using the Hasura CLI Console will capture all Metadata changes in the local file system as the changes are made.

• Use the Hasura CLI Console as your development Console.

  • Disable the Hasura GraphQL default Console.
  • Changes via the CLI Console will be detected and will update the local file system.

• Leverage a version control solution such as GitHub or GitLab as the source of truth for the Metadata configuration.

  • Local files updated by the CLI Console are then committed to the source control solution.

• We recommend retaining the CLI-exported file structure for ease of use.

• Automate deployments using tools such as GitHub Actions, Jenkins, or the CLI-migrations image.

Note

Hasura Cloud users can leverage the GitHub integration to automate deployments.

• Ensure good regression testing is implemented as part of the deployment workflow.
  • graphqurl is a simple tool that can be used to execute GraphQL queries and compare the results to known values.

Use the Enterprise Edition for local development if the other Hasura tiers are Enterprise Edition. Using this image is required to allow for the configuration of Hasura Enterprise features (i.e., read-replicas), so the Hasura CLI will include the configurations in the exported Metadata.

Patterns to avoid

• Don't use the Console or API to export Metadata.

  • The Console and API export JSON files that are not as source-control friendly as YAML (exported by the CLI).

• Don't use the Hasura GraphQL default Console as your development Console.

  • Changes made via the Hasura GraphQL default Console will not capture Metadata changes and can easily cause systems to be out of sync.

• Don't rely on the local file system or the Hasura Metadata database as the source of truth for the Metadata configuration.

  • Local files can easily be unintentionally modified, corrupted, or lost.
  • You can unintentionally modify the Hasura Metadata database through misapplication of Metadata changes.
  • The Hasura Metadata database could be unintentionally lost if you accidentally delete the supporting database or persistent volume.

• Don't manually deploy. While this will work in practice, it will quickly grow beyond a reasonable level of effort as the system's complexity and frequency of deployments increase.

• Don't skip good regression testing as Metadata changes can easily change the fundamental way the Hasura GraphQL Engine operates. Queries you structure differently may return unexpected results. You could modify security policies such as RBAC permissions or allowed queries via Metadata changes that cause unexpected behavior.

• Don't apply Metadata generated from the Community Edition to an Enterprise Edition system that has Enterprise Edition features configured (e.g., read-replicas). Hasura stores these configurations in the Metadata, and the Community Edition cannot configure these features. The resulting exported Metadata will not contain these values, and this Metadata would overwrite the Enterprise Edition configurations if you applied it.