Liquibase 3.x on OpenMRS

I’ve been looking at this issue, to update to a newer version of Liquibase, and have gotten somewhere with it, but I’m getting bitten by this issue in Liquibase itself. Basically, since 3.2.0, Liquibase throws an exception when two files of the same name are found on the classpath.

Ultimately, this causes almost every module to fail assuming they use the standard conventions of putting the liquibase.xml file in the API module, because the liquibase.xml ends up in both the OMOD and the API jar and so is found twice on the code path.

There are five kinds of fixes that occur to me:

  1. In every module, move the liquibase.xml file to the omod module rather than the api module. We could somewhat automate this using the Maven plugin.

  2. Update the Maven plugin to not copy the liquibase.xml file to the omod, since the liquibase.xml file can be loaded from the API jar.

  3. Some sort of change to ModuleClassLoader#isResourceVisible() to ensure that only one copy of liquibase.xml is visible at a time.

  4. Targeting Liquibase 3.1.1, which is at least an update and doesn’t have this issue.

  5. Waiting on Liquibase 4.0.0, which also doesn’t have this issue, but whose release time frame is unclear.

1 and 2 are likely impractical because though we could fix things for the Ref App, it will cause breakages in distributions. 3 lets us update, but feels a bit hackish to me.

I was hoping the community might have some opinions on the best way forward with this.

Option 4. of upgrading to liquibase 3.1.1 seems like the least disruptive approach, as we wait for liquibase 4.0.0 to be released.


It’s not immediately obvious (to me) what the goal of the upgrade is - the ticket doesn’t make any mention of what the purpose is. I can only infer/assume that it’s just to keep our dependencies more up-to-date, and there isn’t a specific function required. Without that knowledge, it’s hard to know whether going to 3.1.1 is an adequate solution, but I agree with @dkayiwa that if it is, that might be the easiest solution since this issue is transitory, and only occurs from [3.2.0, 4.0).

We could also establish new conventions based on this analysis that specifies that poms should be set up to exclude including liquibase.xml in the omod if it is extraneous and works fine just loading from the api jar.

@ibacher do you think having the liquibase file in the omod is the right approach? It feels more appropriate in the API, since the API depends on the data model.


1 Like

Knowing the goal of the upgrade would help with that. @ssmusoke, since you originally requested this, do you have any insight?

@mseaton regarding where the liquibase file belongs, I do think including it in the omod is the right approach, but I get why that’s not an obvious choice. While I get the sense between keeping the database changes near the data model, I think of the liquibase file as being similar to config.xml, i.e., its real use is to get the module running inside the OpenMRS platform. The reason this seems a non-obvious choice, to my mind, is that “omod” in OpenMRS parlance refers to two distinct concepts that aren’t clearly separated in the module structure: 1. the web-related code of a module and 2. the module package itself. I think the liquibase file belongs to 2 and not to 1.

@ibacher as for openmrs-core, would you put the liquibase files in api, web or webapp?

@dkayiwa To be perfectly consistent, I should say webapp, but I also think the situation is somewhat different with the platform itself. That said I have been looking into what it would take to make a separate jar that consists only of the data model, and if I were to do that, I wouldn’t include the liquibase files there.

@ibacher I was trying to leverage liquibase to run SQL files, and I found that OpenMRS was using a very old version

Were you specifically looking to use any of the features added for SQL files in 3.5, i.e. support for contexts or parameter substitution?