Hasura migrations basics¶
Table of contents
Note
For config v1, see Managing Postgres schema migrations and metadata (config v1).
Initializing migrations¶
Install the Hasura CLI or update
to the latest version if current version is < v1.2.0.
Now run:
# create a Hasura project
hasura init
# cd into project dir
# Export current Hasura state
hasura migrate create <init-migration-name> --from-server --endpoint <endpoint>
hasura metadata export --endpoint <endpoint>
# mark the init migration as applied on this server
hasura migrate apply --version "<init-migration-version>" --skip-execution
Generating migrations¶
Open the Hasura console via the CLI
hasura console
As you make changes, migration files will be created and latest metadata will be exported automatically
Create a new migration
hasura migrate create <name-of-migration>
Add SQL manually to the
up.sqlanddown.sqlfiles in the newly created migration’s directory in/migrationsEdit the corresponding metadata manually in
/metadata
Managing migrations¶
For maintaining a clean set of migrations with the possibility to move between different checkpoints in your project’s state it is recommended to clean up intermediate DB migration files and to version control the Hasura project.
Squash migrations¶
Typically while adding a feature a lot of incremental migration files get created for each of the small tasks that you did to achieve the feature.
Once you are confident about the final state of a feature, you can use the
migrate squash command to make a single DB migration file containing all
the intermediate steps required to reach the final state.
hasura migrate squash --name "<feature-name>" --from <migration-version>
# mark the squashed migration as applied on this server
hasura migrate apply --version "<squash-migration-version>" --skip-execution
Add checkpoints¶
As your metadata is exported on every change you make to the schema, once a final state for a feature is reached you should mark it as a checkpoint via version control so that you can get back the metadata at that point.
git commit -m "<feature-name>"
Applying migrations¶
Get the Hasura project with the
migrationsandmetadatadirectories.Apply DB migration files and metadata snapshot
hasura migrate apply --endpoint <server-endpoint> hasura metadata apply --endpoint <server-endpoint>
Your Hasura server should be up and running!
Checking migrations status¶
The following command will print out each migration version present in the migrations
directory along with its name, source status and database status.
# in project dir
hasura migrate status
For example,
$ hasura migrate status
VERSION NAME SOURCE STATUS DATABASE STATUS
1590493510167 init Present Present
1590497881360 create_table_public_address Present Present
Such a migration status indicates that there are 2 migration versions in the local directory and both of them are applied on the database.
If SOURCE STATUS indicates Not Present, it means that the migration
version is present on the server, but not on the current user’s local directory.
This typically happens if multiple people are collaborating on a project and one
of the collaborators forgot to pull the latest changes which included the latest
migration files, or another collaborator forgot to push the latest migration
files that were applied on the database. Syncing of the files would fix the
issue.
If DATABASE STATUS indicates Not Present, it denotes that there are new
migration versions in the local directory which are not applied on the database
yet. Executing hasura migrate apply will resolve this.
