MariaDB Cluster

OpenMRS 2.8.x adds support for MariaDB replication and MariaDB Galera cluster.

Please see https://mariadb.com/docs/connectors/mariadb-connector-j/failover-and-high-availability-with-mariadb-connector-j for a complete documentation of behavior.

Please see our Kubernetes guide for fully automated deployment with MariaDB replication or Galera cluster.

MariaDB replication with read-only replicas

In order for OpenMRS to connect to MariaDB with a primary read-write instance and read-only replicas you need to specify the following environment properties when running a docker image:

OMRS_DB: "mariadb"
OMRS_DB_NAME: "openmrs"
OMRS_DB_HOSTNAME: "primaryHost"
OMRD_DB_URL: "jdbc:mariadb:replication://primaryHost,readReplicaHost1,readReplicaHost2:3306/$OMRS_DB_NAME?autoReconnect=true&sessionVariables=default_storage_engine=InnoDB&useUnicode=true&characterEncoding=UTF-8&transactionReplay=true"

There can be only one primary read-write instance, which is always the first host in the DB URL, and at least one read-only replica.

The read-only transactions are load-balanced between all read replicas. If a read replica fails, it is automatically removed from the connection pool for 60s and all reads are load-balanced between remaining read replicas. If there’s no working read replica then all reads go to the primary instance.

All other transactions are always directed to the primary instance.

If a failure happens during a transaction, it will be transparently replayed on a working node if possible (restrictions apply, see transactionReplay in docs).

If you need to add/remove hosts in the url, you need to restart the instance.

MariaDB Galera cluster

If you want to connect to a fully fledged MariaDB Galera cluster with multiple read-write instances and failover handling you need to specify the following environment properties when running a docker image:

OMRS_DB: "mariadb"
OMRS_DB_NAME: "openmrs"
OMRS_DB_HOSTNAME: "host1"
OMRD_DB_URL: "jdbc:mariadb:loadbalance://host1,host2,host3:3306/$OMRS_DB_NAME?autoReconnect=true&sessionVariables=default_storage_engine=InnoDB&useUnicode=true&characterEncoding=UTF-8&transactionReplay=true"

Typically there are at least 3 read-write replicas in a cluster, but you can add more.

All transactions are load-balanced between all replicas. If an instance fails, it is removed from the connection pool for 60s and all operations are load-balanced between remaining instances.

If a failure happens during a transaction, it will be transparently replayed on a working node if possible (restrictions apply, see transactionReplay in docs).

If you need to add/remove hosts in the url, you need to restart the instance.