Upgrading between dhis2 versions


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;

  1. Better App Functionality
  2. To fix bugs
  3. Better Performance
  4. 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:

  1. Identify the best version to migrate to, depending on your project needs.
  2. Check for potential upgrade issues.
  3. Backup your current database
  4. Drop all SQL views
  5. Follow the upgrade instructions provided by DHIS2.
  6. Install the new DHIS2 version and its required environment
  7. Review your system
  8. Revert upgrade (in cases where an issue occurred)


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.

  1. 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.
  2. 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.
  3. 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.


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;

  1. Study the upgrade notes of the version you are upgrading to. To do so, visit here.
  2. Change the version to the version you are migrating to (e.g. 2.34, 2.29) and then visit the page.
  3. 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.


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.


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.


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.


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.


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;

  1. If you have data entry forms on your system, check to ensure that the entered data before the migration still appears where it should.
  2. 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.
  3. Check that programmed jobs, SQL views, and scripts are working properly.
  4. Check your custom apps and android application to ensure compatibility.


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:

  1. Delete your current DHIS2 WAR file.
  2. Replace the database dump with an untampered one that works seamlessly with the DHIS2 version you are reverting to.
  3. Download the DHIS2 installation file from the DHIS2 download section.
  4. Install the DHIS2 WAR file on your server.
  5. Restart your server and the DHIS2.
  6. Perform a system check to confirm that your instance is back to normal.


If you encounter issues while performing the migration, here are a few steps you can take to resolve them:

  1. Check the server’s error logs for database and server errors.
  2. Inspect the errors to find any pointers to the source of the issue you are experiencing.
  3. 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.
  4. You can contact the DHIS2 team at eHealtheveryone using dhistance@e4email.net or visit here.

Great checklist, thanks for posting.

If I could add anything from experience, it would be take a backup of your existing .war file and keep it if you are upgrading an out of support version. Hopefully you have been keeping things up to date but we have come across clients with systems that are out of date and the .WAR files aren’t available from the official download locations.

Also note that you should always upgrade one major version at a time until you reach the version you want.

Another thing we do is perform the analytics routine and export pivot tables for the various data elements and indicators in the system on the old system to compare with the new system once it’s upgraded. Alternatively set up a QA server with the old version and do a side by side comparison. Ideally you would perform a dummy upgrade on a QA server and test thoroughly for at least a week before going live. We have on more than one occasion found that upgrading the system can introduce regression bugs.

Also bear in mind that enhancements to the rights architecture may mean that users who could perform certain tasks before can no longer perform them after the upgrade, or they may have more rights than you intend in the new system.

Awesome. Thanks Edward.

1 Like