How to handle migrations.IncorrectVersionError

[jdavcs]

In case of this error:

Galaxy has switched from SQLAlchemy Migrate to Alembic (#13513). In some cases, you might see the following error:

galaxy.model.migrations.IncorrectVersionError: Your galaxy database version is incorrect; version 180 is expected. Manual update is required

Solution

If your version in less than 180, you need to checkout a version of the code base that does not include #13513 (merged on March 11) - you can use release_22.01 - and then run the upgrade script:

git checkout release_22.01
sh manage_db.sh upgrade  # upgrade to version 180
git checkout dev 
sh manage_db.sh upgrade  # upgrade to Alembic

If your version is 181, you'll need to checkout a version of the code base that does not include #13513 but does include #13376 (merged on March 9) and downgrade to 180 before upgrading to Alembic:

git checkout da88ded
sh manage_db.sh downgrade --version 180 # downgrade from version 181 to 180
git checkout dev
sh manage_db.sh upgrade  # upgrade to Alembic

Explanation

The referenced version number is the version managed by SQLAlchemy Migrate, stored in the migrate_version table of the galaxy database. Alembic uses a different versioning system (more on that here (needs an update!). For your system to move from one migration versioning system to another, the former needs to be up-to-date - i.e., Alembic requires that your database is current - it must have version 180 (which is the version in the 22.01 release).

If your database version is < 180, you need to first upgrade it. For that, you need to run the manage_db.sh script on a previous version of the code base where the database upgrade is handled by SQLAlchemy Migrate (as suggested, one option is to use release_22.01).

Your database version could also be 181. That would happen only if you pulled in the dev branch between March 9 (after #13376 was merged) and March 11 (before #13513 was merged). In that case, your database is one version ahead of what's required by Alembic. In this case, you'll need to checkout a version of the codebase that includes the changes made in version 181, then downgrade to 180, after which you can proceed to checking out the dev branch and upgrading to Alembic.

[dannon]

@ic4f Thanks for adding the link to this in #13529. I'll go ahead and close the issue since there's no more to be done here, but the text will remain (as a closed issue) for anyone that runs into this.