Upgrading database versions

Major database updates that modify the underlying database schema are incompatible with each other. In most cases, it's possible to migrate an existing database to a newer version without the need to completely reindex it. To do this, we use the alembic database migration tool.

Configuring alembic

Since our databases are single files, there is only minor configuration needed to let alembic know where it is. After cloning the cosima-cookbook repository, edit the alembic.ini file in the root directory. The only important section is the database location:

[alembic]
sqlalchemy.url = sqlite:///path-to-db.db

Note that this is a relative path — an absolute path needs four forward slashes in the URL specification. Additionally, it's recommended that you test the migration on a copy of your database first, and/or save a backup of the older version.

Performing the upgrade

After letting alembic know where to find your database, actually upgrading is as simple as running (from the root directory of the repository):

$ alembic upgrade head

If your database hasn't previously been upgraded by alembic, this will proceed through all of the migrations in turn, which may not be what you want. Otherwise, the command will automatically only apply the necessary migrations.