Development

Before you get started creating migrations, make sure you have read the entirety of the documentation prior to this section.

DANGER ZONE: Migrations are developed in the local host only. You do not apply migrations directly against staging or production. Those migrations are applied solely by the DevOps pipeline via CircleCI or GitHub Actions.

Migration Development in your machine

Branching in localhost is the only way to safely develop migrations.

To create or review a migration:

1. Create a branch (git branch your-branch-name). If you are reviewing a migration, update and check out the branch (git checkout the-branch-name).

2. Run the local hasura cluster, enter ./hasura-cluster start and wait until you see a "migrations finished" message.

3. Once the servers are ready, you may run ./hasura-cluster console or hasura console. Proceed to make changes to the database, then generate the new migration files.

4. If you are reviewing the branch, you may do so here. Make sure there are no errors in the terminal, and that the functionality is there.

5. Save and commit your migration files, then push your changes to your branch in github and make it a PR (no worries, PRs in the database are ignored/not built). If you are reviewing, here is where you make your observations and provide your approval if merited.

6. Wait until another dev downloads your branch, applies your migrations and makes sure it is safe to be merged to staging.

Once the PR branch is reviewed, then it can be merged to master where CircleCI will run the new migration against staging. If the PR is merged against production, then CircleCI will do its thing against production.