Mifos 2.6 Upgrade Instructions

Mifos Versions

• Please read all relevant upgrade instructions for the version of Mifos you are running and above before proceeding with this upgrade - Past Upgrade Instructions
• If you are unsure of the version of Mifos you are using, please refer to Past Releases.

Important Notes

• Labels have been replaced with Customized Text.  Please check your Customized Text after Upgrade to ensure that all labels were converted properly.

Potentially Large DB Changes and Pre-Upgrade Option

Mifos 2.6 contains a substantial amount of database related upgrades.  If you are a small or medium user, this shouldn't amount to much upgrade time and you can ignore this note as the normal Mifos upgrade takes care of everything.  If you are a large/very large user it may matter.  See below to get an idea of how long the upgrade will be for you.

Database Changes

Remove unused currency indexes, add performance indexes and some timestamps.

Benefits

Increase general speed of creating schedules and making payments.
Increase speed of date based processing of schedules and account transactions e.g apply holiday batch job, any reporting on today's transactions
For schedule and customer attendance data, allow the possibility of a speedy incremental ETL job for data warehousing

Also, as a side-effect, there was a 12 to 15% decrease in InnoDB database space usage.

Indication of How Long the Mifos 2.6 upgrade is likely to take

1. Run the following query against your production database to get your 'Data Size' (substituting your mifos database name if it is not 'mifos'):

select sum((t.data_length) / 1048576) as data_size
from information_schema.`tables` t
where table_schema = 'mifos'

2. Looking at the table below, find where you sit against the 3 MFI datasets that we tested against
e.g if your data_size output is 1,000Mb expect the upgrade to take roughly 12-18 mins... if 10,000Mb then approx. 3 hours

Processing the Database Changes Pre-Upgrade

If you decide the upgrade time is too long for you (or you want to pay forward some of the benefits highlighted above), you can run the database change part of the upgrade separately prior to upgrading to mifos 2.6 as the changes work fine on mifos 2.1.x.  Here are the steps.

1. Download the mifos 2.6 zip file and unzip it in a directory of your choosing.

2. Go to the unzipped directory and then go into its db directory.
    Copy the file mifos-db-template.properties to mifos-db.properties
    Edit mifos-db.properties with your mysql database informaton.  Mine is:

username=mifos
password=mifos
defaultSchemaName=mifos
databaseHost=localhost
databasePort=3306

3a. Windows
in a command prompt shell (cmd.exe), go to the db directory mentioned in 2. above and enter the following command:

call bin\expand_db_relG_special.bat

OR
3b. Ubuntu

In the db directory mentioned in 2. above enter the following command to allow you permission to run;
chmod 777 bin/*.sh

Then enter the follow command to run the database changes (if you see 'Liquibase Home is not set.' you can ignore it):

bash bin/expand_db_relG_special.sh

4.  Just leave the upgrade running.  If it is still running coming up to the time the system is need again then

    i) stop mysql which will cause the current upgrade step to fall over (no data damage though).  
    ii) start mysql again
    iii) kick off this upgrade again in your next available down-time slot.  It will continue from where it left off (and so on till it finishes)

5. When you come to upgrading to mifos 2.6, the mifos upgrade process will recognise that the database changes have been done.

Upgrading newer versions of Mifos (2.2.x, 2.3.x, 2.4.x, 2.5.x) to Mifos 2.6.x

Follow the steps below to upgrade newer versions of Mifos (2.2.x, 2.3.x, 2.4.x, 2.5.x) to Mifos 2.6:

STEP 1: Unzip Mifos distribution zip (eg. mifos-v2.6.zip)

NOTE: Do not modify any file using an editor.

mifos-v2.6/
   config/
   db/
     bin/
        contract_db.sh
        expand_db.sh
        liquibase.sh
        undo_contract_db.sh
        undo_expand_db.sh
     changesets/  (contain liquibase xml format database changes - http://www.liquibase.org/manual/changeset)
     lib/ (dependencies required for liquibase)
     sql/ (sql scripts not related to upgrade, only used for creating a new Mifos database)
     mifos-db-template.properties (database configuration template used by liquibase)
   INSTALL
   install-ubuntu.sh
   LICENSE
   mifos.war (deploying war will run expansion script automatically)

STEP 2: Copy db/mifos-db-template.properties to db/mifos-db.properties

STEP 3: Edit db/mifos-db.properties and provide values for db username, password, schema name, machine name and port

STEP 4: Give executable permission for all shell script in db/bin/ folder in case of Unix

STEP 5: Stop jetty

STEP 6: Note down date and time in YYYY-MM-dd HH:mm:ss format (eg. 2012-03-30T0:30:0), this will be required later in case of rollback. Doesn't have to be precise to the minutes, just near to the time before running the upgrade.

STEP 7: Run bin/expand_db.sh or batch file in case of Windows (This step can be skipped for small databases). If expand succeeds, should see "Liquibase Update Successful". If this step fails and you want to continue with previous version of Mifos, run db/bin/undo_expand_db.sh. The usage is undo_expand_db.sh YYYY-MM-ddTHH:mm:ss eg: undo_expand_db.sh 2012-03-30T0:30:0

STEP 8: Confirm the changes by querying the databasechangelog table in the updated Mifos database.

STEP 9: Deploy Mifos, start jetty and test new version of Mifos

STEP 10: Stop jetty

STEP 11: Run db/bin/contract_db.sh. If this step fails and you want to continue with previous version of Mifos, run db/bin/undo_contract_db.sh and db/bin/undo_expand_db.sh. The usage of undo_contract_db.sh is same  as in undo_expand_db.sh mentioned above.

STEP 12: Start jetty, test new version of Mifos, Go live.