UPGRADING BETWEEN DHIS2 VERSIONS
WHAT EXACTLY IS A DHIS2 VERSION MIGRATION?
DHIS2 version migration is the process of upgrading from one DHIS2 version to another. There are different reasons why a migration between two DHIS2 versions will become necessary. Most times, migrations are done to fix a bug, get a new feature, or migrate to a more stable version. There are different reasons why a migration between two DHIS2 versions will become necessary.
Other reasons why a DHIS2 migration is done are;
- Better App Functionality
- To fix bugs
- Better Performance
- User-friendly interfaces
The upgrading process from one version to another involves upgrading the DHIS2 database schema and changing the WAR file.
From DHIS2 version 2.31, the flyway is used as a new system for database migrations as it is integrated into the WAR files and the database schema migration is done for you.
It is best practice to first carry out an upgrade on a test server with the production database and test it out before migrating it.
Steps to follow when migrating between two DHIS2 versions:
- Identify the best version to migrate to, depending on your project needs.
- Check for potential upgrade issues.
- Backup your current database
- Drop all SQL views
- Follow the upgrade instructions provided by DHIS2.
- Install the new DHIS2 version and its required environment
- Review your system
- Revert upgrade (in cases where an issue occurred)
IDENTIFY THE BEST DHIS2 VERSION TO MIGRATE TO
There are different reasons why a migration between two DHIS2 versions will become necessary.
Most times migrations are done to fix a bug, to get a new feature or to migrate to a more stable version.
- If you migrate to another instance to fix bugs in your current one, search through the release notes and DHIS2 Jira issue tracker for the specific releases that have fixes for the bug you are encountering.
- If you are migrating because of newer features, the DHIS2 spotlight page highlights all the new features of major DHIS2 releases. Visit the page to confirm which version includes the features you are looking for. If the particular feature isn’t highlighted in Spotlight then check the release notes of the potential versions you are migrating to for info on the features you need.
- If you are migrating because of instabilities with the version of DHIS2 you are using, the DHIS2 download section indicates the most stable and recent versions of DHIS2 at the time. After receiving this information, it will become clearer if you need to upgrade or downgrade your current version.
CHECK FOR POTENTIAL UPGRADE ISSUES
When newer versions of DHIS2 are released, changes made during development could render the databases of previous versions incompatible with newer ones etc. To avoid such issues, you need to do the following;
- Study the upgrade notes of the version you are upgrading to. To do so, visit here.
- Change the version to the version you are migrating to (e.g. 2.34, 2.29) and then visit the page.
- Follow the instructions in the release notes and if you have further issues, check the corresponding Jira issue for a fix. Their respective fixes accompany most of the potential issues indicated in the upgrade notes.
BACKUP YOUR CURRENT DATABASE
Migrating between two versions requires backing up the current database.
A database backup is also necessary if you need to revert the instance to a previous version in cases where an issue occurs.
To automate the setup of your DHIS2 server or the migration between DHIS2 versions, you can easily visit Dhistance and sign up for free.
DROP ALL SQL VIEWS
It is advisable to drop all SQL views to avoid database integrity issues during the upgrade process, as database tables/columns with associated views cannot be modified.
FOLLOW OTHER UPGRADE INSTRUCTIONS
In the DHIS2 upgrade notes, there are usually instructions to follow when migrating to a particular version. Browse through the upgrade note for the version you migrate to and perform any further step required before migrating.
INSTALL DHIS2 AND ITS ENVIRONMENT
Visit the DHIS2 download section to download the WAR file for the instance you require. After doing this, visit the installation section of the implementer guide for steps to install DHIS2. A server administrator should preferably perform this step.
REVIEW YOUR SYSTEM
After completing your DHIS2 installation and database restoration, a comprehensive review of the system is necessary to ensure that the migration was successful and without issues.
This review is subjective, and its direction is based on the type of project. Create your SQL views again and run analytics to generate your visualizations.
If you made changes to your database tables (by the direction of the upgrade notes) to accommodate a change in the version migrated to, you have to confirm that your change hasn’t affected how your instance functions. For example, if you made changes to a column's name in the data values table, you have to check to ensure that the data on the table still appears in your system.
Do these for whatever scenario you encounter when migrating;
- If you have data entry forms on your system, check to ensure that the entered data before the migration still appears where it should.
- Check that all your metadata still function, especially predictors, indicators, and program rules, majorly any metadata that functions when there is data in the system.
- Check that programmed jobs, SQL views, and scripts are working properly.
- Check your custom apps and android application to ensure compatibility.
REVERT UPGRADE
There will be instances where a DHIS2 migration fails, and the implementer has to revert to the previous stable DHIS2 version. It is important to note that when reverting, one can only revert using the database backup. Any update made on the upgraded database will be lost as rolling back to a previous version of DHIS2 is not possible. In this case, these steps should be followed:
- Delete your current DHIS2 WAR file.
- Replace the database dump with an untampered one that works seamlessly with the DHIS2 version you are reverting to.
- Download the DHIS2 installation file from the DHIS2 download section.
- Install the DHIS2 WAR file on your server.
- Restart your server and the DHIS2.
- Perform a system check to confirm that your instance is back to normal.
FIXING COMMON ISSUES
If you encounter issues while performing the migration, here are a few steps you can take to resolve them:
- Check the server’s error logs for database and server errors.
- Inspect the errors to find any pointers to the source of the issue you are experiencing.
- You can also upload info about your issues, alongside the info from your error logs and the details of your DHIS2 setup on the official DHIS2 Community for further guidance from other DHIS2 users.
- You can contact the DHIS2 team at eHealtheveryone using dhistance@e4email.net or visit here.
USEFUL READING RESOURCES
https://jira.dhis2.org/issues/
https://www.dhis2.org/spotlight
https://www.dhis2.org/downloads
https://github.com/dhis2/dhis2-releases/blob/master/releases/2.34/README.md
https://community.dhis2.org/t/migration-of-database-to-new-server-setup/35068
