Migrations & Metadata (config v2)
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.
This documentation is for Hasura Migrations config v2. For config v3, see
Migrations & Metadata (CI/CD).
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.
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 (config v2).
Advanced use cases
- Auto-apply Migrations/Metadata when the server starts (config v2)
- Writing Migrations manually (config v2)
- Rolling back applied Migrations (config v2)
- Creating a seed data migration (config v2)
