Migrations & Metadata (config v1)¶

Introduction¶

It is typical for developers to use some kind of “migration” tool to track changes to the Postgres schema. Usually the SQL statements used to create the tables, views etc. are stored as a single file or multiple files. Certain tools also let you add an “up” and a “down” step so that you can roll back the changes.

When you connect Hasura to a Postgres database and use the console to “track” a table, a piece of information is added to the Hasura “metadata” (configuration) indicating this table in Postgres should be exposed via GraphQL. Similarly, most of the actions on the console update the Hasura metadata.

In the development phase, you’ll be using the Hasura console to create and track tables, create relationships, add permissions etc. When you need to move to a new environment, it will become quite hard to re-do all these operations using the console again on a fresh database. You might be looking for a way to export the Hasura metadata so that you can apply it on another instance from a CI/CD setup to reproduce the same setup. You might also be looking for a way to do a dev –> staging –> production environment promotion scenario.

Well, you’ve come to the right place to address all these scenarios. Hasura is bundled with a schema/metadata migration system which can be used to declaratively track and version control all the changes happening to the database.

Simple use cases¶

We will split the use cases into two:

1. You’re already using a migration tool for the Postgres schema migrations.

   In this case you only need to manage the Hasura metadata. See Managing Hasura metadata (config v1)

2. You’re not using any migration tool for the Postgres schema.

   See Managing Postgres schema migrations and metadata (config v1)

Advanced use cases¶

• Auto-apply migrations/metadata when the server starts (config v1)
• Writing migrations manually (config v1)
• Rolling back applied migrations (config v1)

Reference documentation¶

• Migration file format reference (config v1)
• Metadata file format reference (config v1)