Liquibase

Testing Liquibase scripts in JUnit tests

It is possible to run liquibase scripts in JUnit tests to verify their correctness. Please see https://github.com/openmrs/openmrs-core/blob/master/api/src/test/java/org/openmrs/util/databasechange/Database1_9_7UpgradeIT.java#L160

Testing Liquibase scripts included in openmrs-api from command line

The openmrs-contrib-liquibaserunner project allows to test Liquibase scripts included in openmrs-api against different DBs. You can clone the project from github running the command:

git clone https://github.com/OpenMRS/openmrs-contrib-liquibaserunner.git

or download as a zip file from here.

Before you can use the tool you need to install maven. Make sure a liquibase database exists and ensure the max_allowed_packet setting on the mysql server is greater than 20 000 000:

create database liquibaserunner default character set utf8;
show global variables like 'max_allowed_packet'; -- Must be bigger than 20000000

In order to execute all tests for scripts included in OpenMRS 1.9.0 run from the project directory:

mvn clean install -Dopenmrs.version="1.9.0" -Ddb.user="root" -Ddb.password="password"

By default Liquibaserunner uses the liquibaserunner MySQL database at localhost:3306. Please make sure that the database exists and can be used exclusively by the tool (all data will be lost).

Default parameters are:

openmrs.version="1.9.0"

db.user="root"

db.password=""

db.url="jdbc:mysql://localhost:3306/liquibaserunner?autoReconnect=true&sessionVariables=storage_engine=InnoDB&useUnicode=true&characterEncoding=UTF-8"

mvp.file="mvp/openmrs_concepts_1.6.5_20120525.xml"

You can override any parameter by adding -Dparameter.name="" to the command line.

Note that you can create a file with one or more of the above parameters (except for openmrs.version) and point to its location with -Dproperties.file="d:/liquibaserunner.properties". Properties set in that file will overwrite any parameters from the command line.

A listing of all available OpenMRS versions can be found in our maven repository. If you specify a version lower than 1.9.0 then you need to add to the command line: -Ppre-1.9

Upgrading MVP dictionary

It is possible to use Liquibaserunner to generate a new version of the MVP dictionary for the selected OpenMRS version.liquibaserunner-standalone.zip

  1. Download and install MySQL. Have it running.
  2. Download and unzip liquibaserunner-standalone (with bundled maven).
  3. Unzip a concept dictionary exported as a MySQL dump from the 1.6.x version (for example openmrs_concepts_1.6.5_20120525.sql) to the liquibaserunner-standalone directory.
  4. Open a console and go to the liquibaserunner-standalone directory.
  5. Run to configure the bundled maven:

    setup
  6. Run:

    mvn clean install -Dtest=UpgradeMVPTest -DfailIfNoTests=false -Dopenmrs.version="1.9.0" -Ddb.user="root" -Ddb.password="password" -Dmvp.file="d:/full/path/to/liquibaserunner-standalone/openmrs_concepts_1.6.5_20120525.sql"

    Adjust user root and password to your MySQL settings. You can also provide a URL to your MySQL. By default localhost:3306/liquibaserunner is used. You can modify that adding the following parameter to the end of the above command:

    -Ddb.url="jdbc:mysql://localhost:3306/liquibaserunner?autoReconnect=true&sessionVariables=storage_engine=InnoDB&useUnicode=true&characterEncoding=UTF-8"

    Change localhost:3306/liquibaserunner as needed. Please make sure that the liquibaserunner database exists and can be used exclusively by the tool (all data will be lost). 
    If you specify openmrs.version lower than 1.9.0 then you need to add to the above command:

    -Ppre-1.9
  7. The generated dictionary can be found in the liquibaserunner database (unless you changed the db.url parameter). It contains only concept tables with creators, voiders, etc. set to the super user. You can dump it to a sql file with any tool such as mysqldump:

    mysqldump -u root -p liquibaserunner > concepts.sql
  8. Concepts.sql will now contain an upgraded version of the MVP dictionary that you can import to your OpenMRS db.

Resources