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 documentation 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>
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.