Overview

This page documents the use of admin tools to perform ad hoc fixes and/or patches for version upgrades. Ad hoc fixes are run to simply correct data conditions in the DB, they are one-time and the mojo should not be expected to retain code for the fix.

Patches have date ranges associated with them so the staging of patches can be successfully tested and deployed to dev, UAT, and then PROD.  All patches should be run in-order and one-at-a-time from the most recently run patch for a database (which ideally should be tracked in the top-level wiki with deployment info by the label "PATCH LEVEL").

Prerequisites

• MySQL database must already exist (e.g. "refsetdb")  
• MySQL database connection parameters must be defined in the properties file specified by "refset.config".
• IMPORTANT: The Tomcat server must not be running while this is invoked.
• To update an existing database (to add fields, etc), make sure to run with -PUpdatedb instead of -PCreatedb

Important Note:

Generally, with PatchData it will be important to update the database prior to running the patch (if any of the changes involve new or changed fields in the data model).  In addition,  there may be a corresponding patch SQL file in admin/src/main/resources, such as patch20170110.sql.

To run a patch manually:

• Run "updatedb" according to documentation in Create Database
• After that, manually run the sql statements in the patch<$date>.sql file.

To run a patch automatically, find the corresponding patch######.csh file in the config/prod/src/main/resources/bin directory:

• e.g. patch20170110.csh
• Copy the script to the top level "bin" directory (parallel to config/ and data/ directories)
• Run the script with a full path name: /home/ihtsdo/refset/bin/patch20170110.csh
• Multiple patch scripts can be run one after another to "catch up" if needed

After done:

• Update the IHTSDO Refset Management & Translation Tool page to indicate the new patch level.

Details

This tool is used to fix a data condition or patch the database for a new release.

Following are some details about the implementation of this tool:

Mojo: AdHocMojo.java (in admin/src/main/resources/java/org/ihtsdo/otf/refset/mojo)
Project: admin
Configuration Parameters

• Profile 
  • "AdHoc"  - for running this

• refset.config - the standard configuration file specified as a -D parameter

• Check the mojo for other parameters, it varies based on the nature of the fix.

Mojo: PatchDataMojo.java (in admin/src/main/resources/java/org/ihtsdo/otf/refset/mojo)
Project: admin
Configuration Parameters

• Profile 
  • "Patch"  - for running this

• refset.config - the standard configuration file specified as a -D parameter

• start - the start date for the first patch to run (from the series), e.g. 20170110
• end - the end date for the last patch to run (may be the same as start), e.g. 20170110

Samples

Sample command line call to run an ad hoc fix:

% cd /home/ihtsdo/refset/code/admin
% mvn install -PAdHoc -Drefset.config=/home/ihtsdo/refset/config/config.properties

Sample command line call to upgrade the 20170110 patch (with prerequisites):

% cd /home/ihtsdo/refset/code/admin
% mvn install -PUpdatedb -Drefset.config=/home/ihtsdo/refset/config/config.properties
% mysql -u $user -p$pwd $db < /home/ihtsdo/refset/code/admin/src/main/resources/patch20170110.sql
% mvn install -PPatch -Drefset.config=/home/ihtsdo/refset/config/config.properties \
   -Dstart=20170110 -Dend=20170110

Troubleshooting

Make sure to fully test ad hoc or patch fixes on an exact copy of the environment intended to run against.  For example, if patching UAT, deploy the current state of UAT to dev, and run the patch and verify proper function.  When upgrading UAT repeat exactly the same process.

References/Links

• n/a