Skip to content

Commit

Permalink
STAND-109 Replace the embedded mysql with mariadb4j
Browse files Browse the repository at this point in the history
  • Loading branch information
k4pran committed Oct 20, 2024
1 parent 60ac6d9 commit 36c0c07
Show file tree
Hide file tree
Showing 20 changed files with 770 additions and 273 deletions.
58 changes: 17 additions & 41 deletions README.md
Original file line number Diff line number Diff line change
@@ -1,6 +1,8 @@
OpenMRS Standalone provides a simplified, all-inclusive installation option with both an embedded database and web server.
Read more at: https://wiki.openmrs.org/display/docs/OpenMRS+Standalone

The current setup uses an embedded MariaDB database with MariaDB4j, while continuing to utilize the MySQL driver for database connectivity. Read more about mariadb4j here: https://github.com/MariaDB4j/MariaDB4j

The master branch of the standalone repo is built by our CI as part of the Platform build at https://ci.openmrs.org/browse/OP and the openmrs-emr2 branch as part of the Reference Application build at https://ci.openmrs.org/browse/REFAPP-OMODDISTRO

## Overview
Expand All @@ -19,7 +21,7 @@ Depending on what OpenMRS software artifact you are releasing, you may need to c

### Increasing maven memory

Increase the maven memory: e.g. export MAVEN_OPTS="-Xms1012m -Xmx2024m -XX:PermSize=556m -XX:MaxPermSize=1012m"
Increase the maven memory: e.g. export MAVEN_OPTS="-Xms1012m -Xmx2024m"

### Running the build in two steps

Expand Down Expand Up @@ -69,7 +71,7 @@ just downloaded

### Other tips

* If running `mvn clean` and `mvn package` second time, ALWAYS check to make sure mysql processes on port 3326 and/or
* If running `mvn clean` and `mvn package` second time, ALWAYS check to make sure MariaDB processes on port 3326 and/or
3328 and/or 33326 are stopped. If you DON'T do that, then the `mvn clean` will not really clean.

* A good command to use is: "pkill -f standalone" (kills anything with "standalone" in the path)
Expand Down Expand Up @@ -124,18 +126,18 @@ NOTE: Using Maven Package will generate the executable jar file in the target fo
## APPLICATION USER INTERFACE

Tomcat Port This is the port at which to run tomcat.
MySQL Port This is the port at which to run mysql
MySQL Port This is the port at which to run MariaDB

File -> Quit This menu item stops tomcat and mysql and then closes the application.
File -> Quit This menu item stops tomcat and MariaDB and then closes the application.
File -> Launch Browser This menu item opens the openmrs login page for the current web application context.
File -> Clear Output This clears the output log in the user interface text area. But does not clear the log file
written on the file system.

Start This button runs tomcat, which will automatically start the mysql database engine if it
was not already running. For the embedded mysql, the first connection automatically starts
the mysql engine.
Start This button runs tomcat, which will automatically start the MariaDB database engine if it
was not already running. For the embedded MariaDB4j, the first connection automatically starts
the MariaDB engine.

Stop This button stops tomcat and then also stops the mysql database engine, without closing the application.
Stop This button stops tomcat and then also stops the MariaDB database engine, without closing the application.


NOTE: Minimizing or Maximizing the application window does not have any effect on the server. The window close icon will stop
Expand All @@ -147,7 +149,7 @@ NOTE: Minimizing or Maximizing the application window does not have any effect o
Running from command line requires the -commandline switch.
e.g. java -jar standalone-0.0.1-SNAPSHOT.jar -commandline

-mysqlport: Use to override the mysql port in the runtime properties file.
-mysqlport: Use to override the MariaDB port in the runtime properties file.
-tomcatport: Use to override the tomcat port in the runtime properties file.
start Use to start the server.
stop Use to stop the server.
Expand All @@ -166,7 +168,7 @@ browser Use to launch a new browser instance.

5. For the section: "Do you want to also add demo data to your database - openmrs? (This option only available if creating new tables.)", just choose what you want.

6. For the section: "Do you currently have a database user other than root that has read/write access to the openmrs database?", Choose Yes, and then enter a "openmrs" and "test" as the user name and password. This account will be created by the embedded database engine. The reason to use 'test' is that when the application starts, it checks for the mysql password and if it is test, it is replaced with a randomly generated 12 character password which is written back to the runtime properties file.
6. For the section: "Do you currently have a database user other than root that has read/write access to the openmrs database?", Choose Yes, and then enter a "openmrs" and "test" as the user name and password. This account will be created by the embedded database engine. The reason to use 'test' is that when the application starts, it checks for the MariaDB password and if it is test, it is replaced with a randomly generated 12 character password which is written back to the runtime properties file.

7. Click "Continue" to go to the next wizard screen, and feel free to fill what you want on this screen.

Expand Down Expand Up @@ -221,37 +223,15 @@ NOTE: Without this folder structure, you will get errors while trying to run the

## DATABASE CONNECTION STRING

jdbc:mysql:mxj://localhost:3316/openmrs?autoReconnect=true&sessionVariables=storage_engine=InnoDB&useUnicode=true&characterEncoding=UTF-8&server.initialize-user=true&createDatabaseIfNotExist=true&server.basedir=database&server.datadir=database/data&server.collation-server=utf8_general_ci&server.character-set-server=utf8

The above default database connection string has all in the openmrs mysql default database connection string plus a
few additional parameters as explained below:

mxj This is required for the MySQL Connector/MXJ utility which we use for embedding mysql
More information about it can be found at: http://dev.mysql.com/doc/refman/5.1/en/connector-mxj.html

server.initialize-user The value of true tells the database engine to create the user account that will be specified
in the openmrs web database setup. This is the account referred to as
connection.username & connection.password in the runtime properties file.

createDatabaseIfNotExist The value of true tells the database engine to create the database if it does not exist.
jdbc:mysql://127.0.0.1:3316/openmrs?autoReconnect=true&sessionVariables=storage_engine=InnoDB&useUnicode=true&characterEncoding=UTF-8

server.basedir This is the directory where the mysql database server will be installed. The default value
is a database folder in the current directory where the executable jar file is located.

server.datadir This is the dirrectory where mysql stores the database. The default value is the data folder
under the database folder in the current directory where the executable jar file is located.

server.collation-server This sets the collation of the database server. If you do not set it to this value, you will
get problems running the openmrs liquibase files. This is because the default value is swedish
collation yet openmrs uses utf8

server.character-set-server This is the character set used by the database server.
The above default database connection string has all in the openmrs mysql default database connection and is used for the MariaDB connection.

NOTE: When creating a new database using the openmrs database setup wizard, remember to replace the default connection string
with the one above in the "Database Connection:" text field.

The embedded mysql database engine is a fully functional database engine that you can connect too using any database
The embedded MariaDB4j database engine is a fully functional database engine that you can connect too using any database
GUI query tools like Navicat, EMS MySQL Manager, etc


Expand Down Expand Up @@ -285,9 +265,5 @@ SUMMARY: Using a single package for all (most) platforms approximately tripples



MySQL MXJ documentation can be found at:
http://dev.mysql.com/doc/refman/5.1/en/connector-mxj.html

Details on how to add or remove platform specific databases can be found at:
http://dev.mysql.com/doc/refman/5.1/en/connector-mxj-usagenotes-packaging.html
http://blog.teamlazerbeez.com/2011/10/03/embedded-mysql-on-java-with-connectormxj-and-64-bit-linux/
MariaDB4j documentation can be found at:
https://github.com/MariaDB4j/MariaDB4j
35 changes: 31 additions & 4 deletions pom-step-01.xml
Original file line number Diff line number Diff line change
Expand Up @@ -35,6 +35,33 @@

<build>
<plugins>
<plugin>
<groupId>ch.vorburger.mariaDB4j</groupId>
<artifactId>mariaDB4j-maven-plugin</artifactId>
<configuration>
<port>33326</port>
<baseDir>${project.build.directory}/emptydatabase</baseDir>
<dataDir>${project.build.directory}/emptydatabase/data</dataDir>
</configuration>

<executions>
<execution>
<id>start-empty-database</id>
<phase>initialize</phase>
<goals>
<goal>start</goal>
</goals>
</execution>
<execution>
<id>stop-empty-database</id>
<phase>process-resources</phase>
<goals>
<goal>stop</goal>
</goals>
</execution>
</executions>
</plugin>

<plugin>
<groupId>org.apache.maven.plugins</groupId>
<artifactId>maven-resources-plugin</artifactId>
Expand Down Expand Up @@ -65,9 +92,9 @@
<id>empty-db-create-schema</id>
<phase>generate-resources</phase>
<configuration>
<driver>com.mysql.jdbc.Driver</driver>
<driver>com.mysql.cj.jdbc.Driver</driver>
<changeLogFile>liquibase-schema-only.xml</changeLogFile>
<url><![CDATA[jdbc:mysql:mxj://127.0.0.1:33326/openmrs?autoReconnect=true&sessionVariables=storage_engine=InnoDB&useUnicode=true&characterEncoding=UTF-8&server.initialize-user=true&createDatabaseIfNotExist=true&server.basedir=${project.build.directory}/emptydatabase&server.datadir=${project.build.directory}/emptydatabase/data&server.collation-server=utf8_general_ci&server.character-set-server=utf8&server.max_allowed_packet=32M]]></url>
<url><![CDATA[jdbc:mysql://127.0.0.1:33326/openmrs?autoReconnect=true&sessionVariables=storage_engine=InnoDB&useUnicode=true&characterEncoding=UTF-8]]></url>
<username>openmrs</username>
<password>test</password>
<verbose>true</verbose>
Expand All @@ -91,9 +118,9 @@
<id>empty-db-add-core-data</id>
<phase>generate-resources</phase>
<configuration>
<driver>com.mysql.jdbc.Driver</driver>
<driver>com.mysql.cj.jdbc.Driver</driver>
<changeLogFile>liquibase-core-data.xml</changeLogFile>
<url><![CDATA[jdbc:mysql:mxj://127.0.0.1:33326/openmrs?autoReconnect=true&sessionVariables=storage_engine=InnoDB&useUnicode=true&characterEncoding=UTF-8&server.initialize-user=true&createDatabaseIfNotExist=true&server.basedir=${project.build.directory}/emptydatabase&server.datadir=${project.build.directory}/emptydatabase/data&server.collation-server=utf8_general_ci&server.character-set-server=utf8&server.max_allowed_packet=32M]]></url>
<url><![CDATA[jdbc:mysql://127.0.0.1:33326/openmrs?autoReconnect=true&sessionVariables=storage_engine=InnoDB&useUnicode=true&characterEncoding=UTF-8]]></url>
<username>openmrs</username>
<password>test</password>
<verbose>true</verbose>
Expand Down
34 changes: 33 additions & 1 deletion pom-step-02.xml
Original file line number Diff line number Diff line change
Expand Up @@ -18,6 +18,32 @@

<build>
<plugins>
<plugin>
<groupId>ch.vorburger.mariaDB4j</groupId>
<artifactId>mariaDB4j-maven-plugin</artifactId>
<configuration>
<port>33326</port>
<baseDir>${project.build.directory}/emptydatabase</baseDir>
<dataDir>${project.build.directory}/emptydatabase/data</dataDir>
</configuration>

<executions>
<execution>
<id>start-empty-database</id>
<phase>initialize</phase>
<goals>
<goal>start</goal>
</goals>
</execution>
<execution>
<id>stop-empty-database</id>
<phase>process-resources</phase>
<goals>
<goal>stop</goal>
</goals>
</execution>
</executions>
</plugin>
<plugin>
<groupId>org.liquibase</groupId>
<artifactId>${liquibase.plugin.artifactId}</artifactId>
Expand All @@ -28,7 +54,7 @@
<configuration>
<driver>com.mysql.jdbc.Driver</driver>
<changeLogFile>${project.build.directory}/liquibase/${liquibase.cieldata.filename}</changeLogFile>
<url><![CDATA[jdbc:mysql:mxj://127.0.0.1:33326/openmrs?autoReconnect=true&sessionVariables=storage_engine=InnoDB&useUnicode=true&characterEncoding=UTF-8&server.initialize-user=true&createDatabaseIfNotExist=true&server.basedir=${project.build.directory}/emptydatabase&server.datadir=${project.build.directory}/emptydatabase/data&server.collation-server=utf8_general_ci&server.character-set-server=utf8&server.max_allowed_packet=32M]]></url>
<url><![CDATA[jdbc:mysql://127.0.0.1:33326/openmrs?autoReconnect=true&sessionVariables=storage_engine=InnoDB&useUnicode=true&characterEncoding=UTF-8]]></url>
<username>openmrs</username>
<password>test</password>
<verbose>true</verbose>
Expand Down Expand Up @@ -74,6 +100,12 @@
<version>${ciel.dictionary.openmrs.version}-${ciel.dictionary.version}</version>
<type>zip</type>
</dependency>
<dependency>
<groupId>mysql</groupId>
<artifactId>mysql-connector-java</artifactId>
<version>5.1.28</version>
<scope>compile</scope>
</dependency>
</dependencies>
</plugin>
</plugins>
Expand Down
34 changes: 30 additions & 4 deletions pom-step-03.xml
Original file line number Diff line number Diff line change
Expand Up @@ -35,6 +35,32 @@

<build>
<plugins>
<plugin>
<groupId>ch.vorburger.mariaDB4j</groupId>
<artifactId>mariaDB4j-maven-plugin</artifactId>
<configuration>
<port>33326</port>
<baseDir>${project.build.directory}/emptydatabase</baseDir>
<dataDir>${project.build.directory}/emptydatabase/data</dataDir>
</configuration>

<executions>
<execution>
<id>start-empty-database</id>
<phase>initialize</phase>
<goals>
<goal>start</goal>
</goals>
</execution>
<execution>
<id>stop-empty-database</id>
<phase>process-resources</phase>
<goals>
<goal>stop</goal>
</goals>
</execution>
</executions>
</plugin>
<plugin>
<groupId>org.liquibase</groupId>
<artifactId>${liquibase.plugin.artifactId}</artifactId>
Expand All @@ -43,9 +69,9 @@
<id>empty-db-update-to-latest</id>
<phase>generate-resources</phase>
<configuration>
<driver>com.mysql.jdbc.Driver</driver>
<driver>com.mysql.cj.jdbc.Driver</driver>
<changeLogFile>liquibase-update-to-latest.xml</changeLogFile>
<url><![CDATA[jdbc:mysql:mxj://127.0.0.1:33326/openmrs?autoReconnect=true&sessionVariables=storage_engine=InnoDB&useUnicode=true&characterEncoding=UTF-8&server.initialize-user=true&createDatabaseIfNotExist=true&server.basedir=${project.build.directory}/emptydatabase&server.datadir=${project.build.directory}/emptydatabase/data&server.collation-server=utf8_general_ci&server.character-set-server=utf8&server.max_allowed_packet=32M]]></url>
<url><![CDATA[jdbc:mysql://127.0.0.1:33326/openmrs?autoReconnect=true&sessionVariables=storage_engine=InnoDB&useUnicode=true&characterEncoding=UTF-8]]></url>
<username>openmrs</username>
<password>test</password>
<verbose>true</verbose>
Expand All @@ -69,9 +95,9 @@
<id>empty-db-followup</id>
<phase>generate-resources</phase>
<configuration>
<driver>com.mysql.jdbc.Driver</driver>
<driver>com.mysql.cj.jdbc.Driver</driver>
<changeLogFile>${liquibase.emptydb.followup.filename}</changeLogFile>
<url><![CDATA[jdbc:mysql:mxj://127.0.0.1:33326/openmrs?autoReconnect=true&sessionVariables=storage_engine=InnoDB&useUnicode=true&characterEncoding=UTF-8&server.initialize-user=true&createDatabaseIfNotExist=true&server.basedir=${project.build.directory}/emptydatabase&server.datadir=${project.build.directory}/emptydatabase/data&server.collation-server=utf8_general_ci&server.character-set-server=utf8&server.max_allowed_packet=32M]]></url>
<url><![CDATA[jdbc:mysql://127.0.0.1:33326/openmrs?autoReconnect=true&sessionVariables=storage_engine=InnoDB&useUnicode=true&characterEncoding=UTF-8]]></url>
<username>openmrs</username>
<password>test</password>
<verbose>true</verbose>
Expand Down
34 changes: 33 additions & 1 deletion pom-step-04.xml
Original file line number Diff line number Diff line change
Expand Up @@ -18,6 +18,32 @@

<build>
<plugins>
<plugin>
<groupId>ch.vorburger.mariaDB4j</groupId>
<artifactId>mariaDB4j-maven-plugin</artifactId>
<configuration>
<port>33328</port>
<baseDir>${project.build.directory}/demodatabase</baseDir>
<dataDir>${project.build.directory}/demodatabase/data</dataDir>
</configuration>

<executions>
<execution>
<id>start-demo-database</id>
<phase>initialize</phase>
<goals>
<goal>start</goal>
</goals>
</execution>
<execution>
<id>stop-demo-database</id>
<phase>process-resources</phase>
<goals>
<goal>stop</goal>
</goals>
</execution>
</executions>
</plugin>
<plugin>
<artifactId>maven-antrun-plugin</artifactId>
<version>1.8</version>
Expand Down Expand Up @@ -45,7 +71,7 @@
<configuration>
<driver>com.mysql.jdbc.Driver</driver>
<changeLogFile>${liquibase.demodata.filename}</changeLogFile>
<url><![CDATA[jdbc:mysql:mxj://127.0.0.1:33328/openmrs?autoReconnect=true&sessionVariables=storage_engine=InnoDB&useUnicode=true&characterEncoding=UTF-8&server.initialize-user=true&createDatabaseIfNotExist=true&server.basedir=${project.build.directory}/demodatabase&server.datadir=${project.build.directory}/demodatabase/data&server.collation-server=utf8_general_ci&server.character-set-server=utf8&server.max_allowed_packet=32M]]></url>
<url><![CDATA[jdbc:mysql://127.0.0.1:33328/openmrs?autoReconnect=true&sessionVariables=storage_engine=InnoDB&useUnicode=true&characterEncoding=UTF-8]]></url>
<username>openmrs</username>
<password>test</password>
<verbose>true</verbose>
Expand Down Expand Up @@ -85,6 +111,12 @@
<artifactId>identity-insert</artifactId>
<version>1.2.1</version>
</dependency>
<dependency>
<groupId>mysql</groupId>
<artifactId>mysql-connector-java</artifactId>
<version>5.1.28</version>
<scope>compile</scope>
</dependency>
</dependencies>
</plugin>
</plugins>
Expand Down
Loading

0 comments on commit 36c0c07

Please sign in to comment.