DHIS upgrade from 2.10 to 2.15 with MySQL on Windows

Background

This tutorial describes how to UPGRADE dhis from 2.10 to 2.15 with MySQL on Windows.

The target audiences are clients deploying dhis2 on MySQL. You dont need this tutotial if you are using postgresSQL or other supported RDBMS

DHIS is acronym for District Health Information Software. It is HMIS that allows you to manage aggregate with a flexible data model. You can also use dhis2 to collect, manage and analyse transactional, case-based data records.

DHIS 2 is free and open source software released under the liberal BSD license. It is developed in Java and runs on any platform with a JRE 7 installed. DHIS 2 is web-based and follows HTML 5 standards. You can download the WAR file and drop it into a Web container like Tomcat.

The DHIS2 community is increasing with developers from more countries. Supports from the developers to issues and bugs are rapid and fixes area almost immediate or included in the next release.

See more here http://www.dhis2.org/overview


Introduction
A client requested i should upgrade their DHIS from 2.10 to 2.15 on MySQL Windows x64 because they want to take advantage of the many advanced features the new release bundled with.
They have been running dhis2 for over 2 years with huge institutional data including aggregate and patient/primary data.
Upgrading DHIS2 to a higher build/release have never been any challenging until recent release 2.15.

I was able to complete the upgrade after some days of work and reading and everything seems to be working fine.





Steps:
1.Download the latest/stable DHIS2.war http://www.dhis2.org/downloads

Note: In my own case i downloaded the source code with bazaar and built using maven.
To do this you must install bazaar (version control system)
open DOS command and enter the following command
C: > mkdir dhis2
        cd dhis2
        bzr init-repo --tree
        lp:~dhis2-devs-core/dhis2/2.15

        cd dhis2/dhis2
        mvn clean install

after successful build copy the dhis2.war

2. Download the upgrade script
3. Deploy the war file on tomcat

Issues 1:
Dhis2 was not startted

Resolution;
I updated the following tables and dhis2 deployed and started after looking at the source codes
1. UPDATE dataelementcategory set datadimension=FALSE where datadimension IS
NULL;
2. UPDATE dataelementcategory set dimensiontype='disaggregation';
3. UPDATE categorycombo set skiptotal = FALSE;

Issues 2:
The analytics and data mart generation aborting

Resolution
When i checked the log i discovered the problem was partly dhis2 and partly mysql
Maximum number of indexes allowable for MySQL object is 64. One of the indexes exceeds 64 and MySQL threw the error. Dhis2 aborts the process.

To resolve this i had three (3) options
1.
Migrate from MySQL to PostgresSQL. PostgresSQL happened to be the favourite RDBMS for DHIS2 as i keep battling with DHIS2/MySQL compatibility. The truth of the matter is DHIS2 is not fully compatible with MySQL as the DHIS2 site presents without some code tweakings.

2.
Trace and trim the length of the table indexes from the code if more than 64 in length. I found the problem from this method...

private void createIndexes( List<AnalyticsTable> tables )
    {
        ConcurrentLinkedQueue<AnalyticsIndex> indexes = new ConcurrentLinkedQueue<AnalyticsIndex>();
     
        for ( AnalyticsTable table : tables )
        {
            List<String[]> columns = table.getDimensionColumns();
         
            for ( String[] column : columns )
            {
                indexes.add( new AnalyticsIndex( table.getTempTableName(), column[0] ) );
            }
        }
     
        log.info( "No of indexes: " + indexes.size() );
     
        List<Future<?>> futures = new ArrayList<Future<?>>();

        for ( int i = 0; i < getProcessNo(); i++ )
        {
            futures.add( tableManager.createIndexesAsync( indexes ) );
        }

        ConcurrentUtils.waitForCompletion( futures );
    }


3.
Configure MySQL to allow more that 64 length table indexes



Since my clients have huge investment using MySQL, adjusting DHIS2 code is out of it, i decided to go for option 3.

Follow the steps below to configure MySQL to have 128 table indexes creation

To build/configure and install you need the following tools
a. cmake  www.cmake.org
b. bison
c. c++ compiler. (i have MS Visual studio 11 on my system. That should be enough)

1. Download and unzip the MySQL source code distribution  
    http://dev.mysql.com/downloads/mysql/
    I used the developmental release 5.7.4 m14 for MS Windows

2. open command and cd to where you unzipped the distribution
 
   cd C:\mysql_server
    C:\mysql_server> mkdir bld
    C:\mysql_server> cd bld
    C:\mysql_server\bld> cmake .. -G "Visual Studio 11 Win64" -DMAX_INDEXES=128 -DBUILD_CONFIG=mysql_release

    wait until compilation finishes then run the following

    C:\mysql_server\bld> devenv MySQL /build RelWithDebInfo /project initial_database /project package

    wait (may take a while) ensure the build is successful.

    The build created a zipped file named mysql-5.7.4-m14-winx64

    Unzip the file and navigate to the bin from the command.
 
    Start MySQL with mysqld --console
    Restore the dump file into the new MySQL
 
    Stop and start DHIS2 from tomcat
 
    Run the anaylitics and data mart

    Success without error.