Support MariaDB JDBC url and MariaDB driver

jonathan · May 26, 2025, 11:20am

Hi Everyone

As part of improving standalone efforts (GSOC 2025) within the OpenMRS, I would like to propose that we officially support the MariaDB JDBC URL and Driver in addition to the existing MySQL setup.

Problem:

Currently, OpenMRS primarily configures JDBC connections using MySQL conventions

jdbc:mysql://localhost:3306/openmrs

However, when using MariaDB, using the MySQL JDBC URL has lead to compatibility issues with recent versions of the MariaDB server (11.4.5). For instance, am encounter errors such as:

java.sql.SQLSyntaxErrorException: Unknown column ‘RESERVED’ in ‘WHERE’

which call for a solution discussed here

This arises because MySQL and MariaDB have diverged slightly in metadata handling, and the MySQL Connector/J driver does not guarantee compatibility with newer MariaDB versions.

Proposed Solution:

Allow specifying MariaDB-compliant JDBC URLs in runtime properties and configuration wizards

jdbc:mariadb://localhost:3306/openmrs

Include the official MariaDB JDBC Driver (com.mysql.cj.jdbc.Driver) as a supported dependency during setup (openmrs core).
Detect database type (MariaDB vs MySQL) early in setup to avoid known issues with reserved word lookups and changelog parsing in Liquibase.

For the existing drivers supported u can check out here

github.com/openmrs/openmrs-core

api/src/main/java/org/openmrs/util/DatabaseUtil.java

4a61d8a01


      
          	public static String loadDatabaseDriver(String connectionUrl, String connectionDriver) throws ClassNotFoundException {
          		if (StringUtils.hasText(connectionDriver)) {
          			Class.forName(connectionDriver);
          			log.debug("set user defined Database driver class: " + connectionDriver);
          		} else {
          			if (connectionUrl.contains("mysql")) {
          				Class.forName("com.mysql.cj.jdbc.Driver");
          				connectionDriver = "com.mysql.cj.jdbc.Driver";
          			} else if (connectionUrl.contains("hsqldb")) {
          				Class.forName("org.hsqldb.jdbcDriver");
          				connectionDriver = "org.hsqldb.jdbcDriver";
          			} else if (connectionUrl.contains("postgresql")) {
          				Class.forName("org.postgresql.Driver");
          				connectionDriver = "org.postgresql.Driver";
          			} else if (connectionUrl.contains("oracle")) {
          				Class.forName("oracle.jdbc.driver.OracleDriver");
          				connectionDriver = "oracle.jdbc.driver.OracleDriver";
          			} else if (connectionUrl.contains("jtds")) {
          				Class.forName("net.sourceforge.jtds.jdbc.Driver");
          				connectionDriver = "net.sourceforge.jtds.jdbc.Driver";

This file has been truncated. show original

I’d love to hear your feedback or if others have run into this issue.

cc @ibacher @wikumc @dkayiwa @burke @mseaton @grace

sharif · May 26, 2025, 11:28am

MariaDB 11.4.5 of recent introduced changes that are incompatible with MySQL 8 drivers. So i think for some reasons, It makes sense to include it.

mherman22 · May 26, 2025, 12:04pm

Definitely worth supporting, but we should also be keen just incase of Liquibase compatibility issues, driver dependencies, and ensuring backward compatibility with MySQL users. Happy to help verify this across test setups.

dkayiwa · May 26, 2025, 1:23pm

What are your thoughts on having MariaDB4J support a lower version of MariaDB? At least the one we support in O3?

jonathan · May 27, 2025, 12:08pm

Oh yes, that would have been a great idea. However, earlier versions had compatibility issues with M1 and M2 Mac silicon chips. That’s why they opted for a newer version (11.4.5).

Note: Older versions of MariaDB4j lacked support for Apple Silicon (M1, M2+), which remains a critical issue on those machines.

jonathan · May 28, 2025, 3:33pm

On trying the lower version of MariaDB4j (3.1.0) using MariaDB binaries 10.11.5 on a linux machine 20.0.4 using mysql jdbc url and driver

Am getting liquibase errors INFO - Slf4JLogger.log(43) |2025-05-28T18:19:14,864| Marking ChangeSet: "liquiba - Pastebin.com still connected to mariadb

cc @dkayiwa @wikumc