Database upgrade in Rally

Information for users

Rally supports DB schema versioning (schema versions are called revisions) and migration (upgrade to the latest revision).

End user is provided with the following possibilities:

• Print current revision of DB.

  rally db revision
  

• Upgrade existing DB to the latest state.

  This is needed when previously existing Rally installation is being upgraded to a newer version. In this case user should issue command

  rally db upgrade
  

  AFTER upgrading Rally package. DB schema will get upgraded to the latest state and all existing data will be kept.

  WARNING Rally does NOT support DB schema downgrade. One should consider backing up existing database in order to be able to rollback the change.

Information for developers

DB migration in Rally is implemented via package alembic.

It is highly recommended to get familiar with it's documentation available by the link before proceeding.

If developer is about to change existing DB schema they should create a new DB revision and a migration script with the following command.

alembic --config rally/common/db/sqlalchemy/alembic.ini revision -m <Message>

or

alembic --config rally/common/db/sqlalchemy/alembic.ini revision --autogenerate -m <Message>

It will generate migration script -- a file named <UUID>_<Message>.py located in rally/common/db/sqlalchemy/migrations/versions.

Alembic with parameter --autogenerate makes some "routine" job for developer, for example it makes some SQLite compatible batch expressions for migrations.

Generated script should then be checked, edited if it is needed to be and added to Rally source tree.

WARNING Even though alembic supports schema downgrade, migration scripts provided along with Rally do not contain actual code for downgrade.