Migrations with a database with an existing migration system

This guide will help you setup Hasura specific migrations in case you’re working with an existing database that already has its database migration tooling.

In this case, you’ll be using Hasura migrations only to track changes to the Hasura metadata which affect your GraphQL schema and not the underlying database.

Step 0: Take a note of your GraphQL engine endpoint

Let’s say you’ve deployed the GraphQL engine on Heroku, then this endpoint is: http://my-graphql.herokuapp.com. In case you’ve deployed this using Docker the URL might be http://xx.xx.xx.xx:8080.

Step 1: Install the Hasura CLI

In your terminal enter the following command:

curl -L https://cli.hasura.io/install.sh | bash

This will install the Hasura CLI in /usr/local/bin. You might have to provide your sudo password depending on the permissions of your /usr/local/bin location.

Open your linux shell and run the following command:

curl -L https://cli.hasura.io/install.sh | bash

This will install the Hasura CLI tool in /usr/local/bin. You might have to provide your sudo password depending on the permissions of your /usr/local/bin location.

Note

You should have git bash installed to use Hasura CLI. Download git bash using this link. Also, make sure you install it in MinTTY mode, instead of Windows’ default console.

Download the hasura installer:

Note: Please run the installer as Administrator to avoid PATH update errors. If you’re still getting a “command not found” error after installing Hasura CLI, please restart git bash.

Step 2: Set up a project directory

Skip this step if you already have a project directory.

hasura init --directory my-project --endpoint http://my-graphql.herokuapp.com

Step 3: Open the console via the CLI & disable Postgres schema changes

Instead of using the console at http://my-graphql.herokuapp.com/console you should now use the console by running:

# Without access key
hasura console

# With access key
hasura console --access-key mysecretkey

Step 4: Disable database schema modifications

Since you are using other tools to manage database migrations, you should disable the tools on the Hasura console which modify the database schema to prevent edits to the database schema. But, you can still do actions related to the GraphQL schema, like tracking a table or creating/editing relationships or modifying permissions, as they are managed by Hasura metadata.

To disable schema modifications, head to Data -> Migrations on the console and then disable the toggle Allow postgres schema changes.

Step 5: Track a table, or modify a relationship/permission

As you use the console to track/untrack tables, views or update relationships and permissions you’ll see how the metadata file changes automatically at migrations/metadata.yaml.

Step 6: Apply the metadata to another instance of GraphQL engine

  • Edit config.yaml and change the endpoint to another instance, say https://my-another-graphql.herokuapp.com

    # config.yaml
    endpoint: https://my-another-graphql.herokuapp.com
    
  • Apply metadata present in the migrations/metadata.yaml on this new instance:

    hasura metadata apply
    

Step 7: Other metadata commands

To clear, export, apply metadata refer to hasura metadata command.