Database Upgrades

Mifos uses MySQL database for the "back end". When deploying a new version of Mifos, the database schema is automatically upgraded (columns/tables/indexes added/changed, etc).

See code in

How to Properly Script Database Changes

In summary, here is how a developer should go STEP-BY-STEP about developing a change which involves changes to the database schema or preloaded data:

Mifos DB Upgrade

DB upgrade in Mifos is done using Liquibase. Liquibase change sets are specified in XML. Liquibase generates equivalent SQL and applies the change sets to DB. See FAQ.

Locate your change set file
Mifos uses one file per release to capture the change sets. The file names follow the convention changelog-<RELEASE_NAME> and can be found in db/src/main/resources/changesets/ folder.
For example changelog-Elsie_F.xml  contains all db change sets in release Elsie_F. This file is available in source control for reference.   

Add a new change set file in case of new release (Optional step)
If change set file corresponding to the release say ReleaseX does not exist, create a new file by name changelog-ReleaseX.xml and include the new file in changelog-master.xml using <include> tag. The only content allowed in changelog-master.xml are the <include> tags.

Choose the context of change set
Change set context can be one of “expansion” or “contraction”. Any addition to DB like create table/index/key, insert/update statements are expansion operations. Removal of anything existing in DB is a contraction operation. Incidentally changelog-Elsie_F.xml contains only expansions. A rename operation needs to be split into and expansion and contraction.

Choose Id of change set
The change set id follows the convention MIFOS-<JIRA_NUMBER>_<X>, where X is a number starting from 1. Changes also have an author name which is the same as the display name in source control. A change set should contain either a DML or a DDL and not a mix.

If Jack and Jill works on the story 3703 which will be part of release Elsie_F, with Jack committing an expansion first and Jill committing an expansion followed by a contraction, we will see the  change sets with following identifications in changelog-Elsie_F.xml in the given order.

<changeSet id="MIFOS-3703_1" author="Jack" context="expansion">...

<changeSet id="MIFOS-3703_1" author="Jill" context="expansion">...

<changeSet id="MIFOS-3703_2" author="Jill" context="contraction">...

Complete your change set by writing rollback

Liquibase can generate rollback statements for the most obvious operations like create table. But for other operations like an insert or update with auto generated primary keys, the author needs to provide the rollback statements as well. Its a good practice to explicitly specify the rollback section in each change set.

As usual run DatasetUpgradeUtil if this change set is required in acceptance tests, build your application, run tests and commit.