Migrations & Metadata Introduction
Hasura needs two pieces of information which work together to describe your Hasura setup
- Migrations - Representing the underlying database schema.
- Metadata - Describing the exposed Hasura GraphQL API and all other configuration.
Keep track of your database schema over time.
Hasura Migrations are a SQL representation of the state of your database schema which can be used to keep track of, update, roll-back or move your schema using the Hasura CLI.
They are automatically generated in a series of Unix nanosecond timestamped directories consisting of
down.sql files in pure SQL syntax, which describe to Hasura Server both how to create, (
up.sql) and how to roll back
down.sql) each of your database changes step-by-step.
When these files are committed to version control, your database schema state can be kept in-sync with your codebase.
When used in combination with CI/CD, changes to your database schema can automatically and elegantly be applied to your app's development, staging or production versions.
migrations directory created with the Hasura CLI:
└─ 📂 default
└─ 📂 1654696186008_init
└─ 📄 up.sql
└─ 📂 1654698227514_create_table_public_address
├─ 📄 down.sql
└─ 📄 up.sql
The configuration of your Hasura Server
Hasura Metadata is a representation of the configuration of the Hasura Server. From actions to databases and their tables, to permissions, event triggers and API limits, everything regarding the config of the Hasura Server is represented in Metadata.
Metadata can also be tracked with version control, allowing your Hasura Metadata to be kept in-sync with your code and database schema changes.
The state of Hasura Metadata is managed via snapshots of the state of the Hasura Server Metadata configuration. These snapshots can be applied as a whole, using the Hasura CLI to the Hasura Server.
metadata directory created with the Hasura CLI:
├─ 📂 databases
│ ├─ 📂 default
│ │ └─ 📂 tables
│ │ ├─ 📄 public_address.yaml
│ │ ├─ 📄 public_author.yaml
│ │ ├─ 📄 public_article.yaml
│ │ └─ 📄 tables.yaml
│ └── 📄 databases.yaml
├─ 📄 actions.graphql
├─ 📄 actions.yaml
├─ 📄 allow_list.yaml
├─ 📄 api_limits.yaml
├─ 📄 cron_triggers.yaml
├─ 📄 graphql_schema_introspection.yaml
├─ 📄 inherited_roles.yaml
├─ 📄 network.yaml
├─ 📄 query_collections.yaml
├─ 📄 remote_schemas.yaml
├─ 📄 rest_endpoints.yaml
└─ 📄 version.yaml
Migrations and Metadata follow their own versioning scheme separate to the that of the Hasura Server and CLI. This
documentation is for the latest Hasura Migrations
config v3, supported from
Setting up migrations
- Advanced Hasura - Learn Tutorial.