Database upgrade/downgrade in Rally

Information for users

Rally supports DB schema versioning (schema versions are called revisions) and migration (upgrade to later and downgrade to earlier revisions).

End user is provided with the following possibilities:

  • Print current revision of DB.

    rally-manage 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-manage db upgrade
    

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

  • Downgrade existing DB to a previous revision.

    This command could be useful if user wants to return to an earlier version of Rally. This could be done by issuing command

    rally-manage db downgrade --revision <UUID>
    

    Database schema downgrade MUST be done BEFORE Rally package is downgraded. User must provide revision UUID to which the schema must be downgraded.

Information for developers

DB migration in Rally is implemented via package alembic.

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

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

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

It will generate migration script – a file named <UUID>_<Message>.py located in rally/common/db/sqlalchemy/migrations/versions. Generated script should then be checked, edited if it is needed to be and added to Rally source tree.