Migrations automatically update existing Submitty installations and existing Submitty courses to work with the latest release of Submitty.
The migrations are applied automatically when you run:
See also: System Administration / Update Submitty
Manually Applying Migrations
To manually run or apply all new, unapplied migrations to your system and existing courses you can run:
sudo python3 /usr/local/submitty/GIT_CHECKOUT/Submitty/migration/migrator.py migrate
Migrations are run in chronological order.
After a migration is applied, the status is stored in the master database (for system or master database migrations) or the course database (for course migrations).
To see additional options, run:
sudo python3 /usr/local/submitty/GIT_CHECKOUT/Submitty/migration/migrator.py -h
Rolling Back or Reverting a Migration
It can be useful during development to rollback or undo a migration. The commands below will undo the most recent migration (in chronological order) to the system installation, master database, or course database, respectively:
sudo python3 /usr/local/submitty/GIT_CHECKOUT/Submitty/migration/migrator.py -e system rollback
sudo python3 /usr/local/submitty/GIT_CHECKOUT/Submitty/migration/migrator.py -e master rollback
sudo python3 /usr/local/submitty/GIT_CHECKOUT/Submitty/migration/migrator.py -e course rollback
Writing New Migrations
If your bugfix or new feature requires a change to the system installation, or the master or course database, or the course directory or file structure:
You should make the necessary edits to build a new system from scratch in the relevant files, e.g.:
GIT_CHECKOUT/Submitty/.setup/install_system.sh, or the files in
Or make changes to the complete database schema(s):
And you should also prepare a migration file of the appropriate type (
course) to update an existing system and existing courses. A migration is a python file with 2 functions,
up(called for the
down(called for the
rollbackcommand). Run the appropriate command below to create the template with the appropriate function signatures:
sudo python3 /usr/local/submitty/GIT_CHECKOUT/Submitty/migration/migrator.py -e system create <MY_MIGRATION_NAME>
sudo python3 /usr/local/submitty/GIT_CHECKOUT/Submitty/migration/migrator.py -e master create <MY_MIGRATION_NAME>
sudo python3 /usr/local/submitty/GIT_CHECKOUT/Submitty/migration/migrator.py -e course create <MY_MIGRATION_NAME>
A new file will be created in the appropriate subfolder of
/usr/local/submitty/GIT_CHECKOUT/Submitty/migration/migrations/. The file will be named with the current date (year, month, day, hour, minute, second) and migration name string you supplied. The filename pattern will allow the migration system to chronologically sort your changes relative to existing & future changes.
See the existing migrations for examples.
NOTE: In general, your
downmigration should only undo the necessary changes to make earlier versions of the Submitty software work. For example, if your migration is adding a column to an existing table in the database, it is probably not necessary or desirable to delete that data in the
downfunction. We don’t want to lose any data since we likely plan to return to this state in the future. Your
downfunction may be empty.
Thus, it is important to ensure that the
upmigration can be re-run. For example, your
upfunction should not crash on adding the column if the column already exists.