Migrations & Metadata

Introduction

It is a typical requirement to export an existing Hasura “setup” so that you can apply it on another instance to reproduce the same setup. For example, to achieve a dev -> staging -> production environment promotion scenario.

Note

This documentation is for Hasura migrations config v3, supported from v2.0.0-alpha.1. (See upgrade guide).

For config v2, see Migrations & Metadata.

How is Hasura state managed?

Hasura needs 2 pieces of information to recreate your GraphQL API, the underlying PG database schema and the Hasura metadata which is used to describe the exposed GraphQL API.

The Hasura CLI lets you manage these pieces of information as you build your project via:

Database migration files

The state of your PG database is managed via incremental SQL migration files. These migration files can be applied one after the other to achieve the final DB schema.

DB migration files can be generated incrementally and can by applied in parts to reach particular checkpoints. They can be used to roll-back the DB schema as well.

Note

You can choose to manage database migrations using external tools like knex, TypeORM, Django/Rails migrations, etc. as well.

Hasura metadata files

The state of Hasura metadata is managed via snapshots of the metadata. These snapshots can be applied as a whole to configure Hasura to a state represented in the snapshot.

Hasura metadata can be exported and imported as a whole.

Setting up migrations

See Setting up Hasura migrations.