OpenMRS Database Migrator Tool

A growing requirement in countries across the world that implement OpenMRS is the need to migrate OpenMRS databases. There are usually a number of different reasons for this, whether it be:

• Upgrading version of OpenMRS
• Migrating to an OpenMRS distro such as Bahmni or RefApp
• Harmonizing metadata across a region

Usually implementers rely on OpenMRS's built in migration scripts for the first one, but the other two usually require custom scripts be implemented for the specific project or region.

The aim of this tool is to fill that gap by being a configurable tool that will allow implementers to easily migrate their OpenMRS databases in whichever way is needed.

Overview

Dependencies

Java 8 needs to be installed for this application to run.

Usage

To build an executable JAR file run:

./gradlew build

To run the SpringBoot application run:

./gradlew bootrun

This app uses the Spotless code formatter to apply the Google Java Format rules to the code base.

If you find yourself with linting exceptions, to automatically resolve all issues try running

./gradlew spotlessApply

How to run the tool

First create the merge database:

CREATE DATABASE `ETL_MERGE_DATABASE` CHAR SET uf8;

Then load one of the dumps into ETL_MERGE_DATABASE. After that run the following script:

use `ETL_MERGE_DATABASE`;

insert into person_attribute_type
    (name, description, searchable, creator, date_created, retired, uuid) values
    ('Source DB ID', 'ID from source database', false, 1, curdate(), false, '8d793bee-c2cc-11de-8d13-0010c6dffd23');

To execute the setup run:

java  -jar migrator.jar setup

To merge OpenMRS databases run:

java -jar migrator.jar run

To list available subcommands run:

java -jar migrator.jar -h

This will run PDI transformations using ETL_SOURCE_DATABASE as the input database. The output will be saved in a database referenced by ETL_MERGE_DATABASE.

Configuration

The tool uses the following variables that can be configured either through system properties or the PDI kettle.properties file:

ETL_TEST_DATABASE_CONNECTION=true
ETL_SOURCE_DATABASE=egpaf
ETL_MERGE_DATABASE=merge_db
ETL_DATABASE_HOST=127.0.0.1
ETL_DATABASE_PORT=3306
ETL_DATABASE_USER=migrator
ETL_DATABASE_PASSWORD=

To specify one of the variables as a system property use the following syntax:

java -DETL_DATABASE_USER=otheruser -jar migrator.jar run

Note that system properties take precedence over kettle.properties.

Tips to keep in mind

References

Technologies used

• Java 8
• Gradle (build tool)
• SpringBoot
• SpringMVC Web technologies
• Thymeleaf Page Layouts
• Pentaho Data Integration (PDI)

Folder Structure

Architecture