Migrations

When the data classes in Quetz are modified (for example, a column is added, remove or updated), the database need to be upgraded while keeping the stored data. This cane be done automatically, using migrations. Quetz uses alembic to handle migrations.

Note

Before running any of the commands below, you need to make sure that your database is backed up. The backup process depends on the infrastrcuture, but in the simplest case it may involve the dump of the whole database (using pg_dump for example).

Migrating database

When you install a new version of Quetz or Quetz plugin, you should apply the provided migrations using the quetz init-db command. For example, assuming that your deployment is in deployment_dir folder:

quetz init-db deployment_dir

Adding new migrations

Once you modified your data models in Quetz, you can autogenerate the appropriate migrations using make-migrations command:

quetz init-db deployment_dir # to make sure that the db is up-to-date
quetz make-migrations deployment_dir --message "my revision message"

This should create a new file in quetz/migrations/versions directory, which you can then add to the git repository. Then you can apply the migrations the standard way:

quetz init-db deployment_dir # to make sure that the db is up-to-date

Note

For running unit test there is no need to create the migrations, the testing framework will create all tables automatically for you. However, if you want to run the tests with the migrations, you can configure it with env variable: QUETZ_TEST_DBINIT=use-migrations pytest quetz

Initializing migrations for plugins

To use migrations in plugins, you need to initialize them. Our cookiecutter template will create the necessary backbone for you, you will just need to define your models in the db_models.py file of plugin directory, and then run the command:

quetz make-migrations deployment_dir --message "initial revision" --initialize --plugin quetz-plugin_name

This should create a new migration script in PLUGIN_DIR/migrations/versions.

Note

If you want to add the migration script to you working directory, you need to install the plugin using the development mode: pip install -e PATH_TO_PLUGIN

As always the quetz init-db will upgrade automatically your database to reflect the data models defined in the plugin.

Adding migrations for plugins

When you change the data model in the plugin, you can create the required migrations using the same quetz make-migrations command, but without --initialize:

quetz make-migrations deployment_dir --message "second revision"  --plugin quetz-plugin_name