Database Replication and Clustering

ObjectDB supports master-slave replication (cluster). When replication (or clustering) is used,
the same database is managed on multiple machines (nodes), possibly in different geographic locations. This could help in achieving high availability, fault tolerance and prompt disaster recovery.

In master-slave replication, the master node manages the main (master) database, which supports Read / Write operations. The other (slave) nodes in the cluster manage identical copies of the same database, which are limited to READ operations. Any update to the master database is automatically propagated to the slave databases, keeping all the slave databases in the cluster synchronized with the master database.

Setting a Master Database

A master ObjectDB database is an ordinary database, which is managed on an ordinary ObjectDB database server. Any ObjectDB database on any server (but not in embedded mode) can function as a master database in a cluster. Recording has to be enabled, but no other preparations or settings are required.

Setting Slave Databases

Setting slave databases is very easy and only requires running an ObjectDB database server with appropriate <replication> elements in the configuration:

<server>
    <connection port="6001" max="100" />
    <data path="$objectdb/db-files" />
    <replication url="objectdb://localhost:6000/my.odb;user=a;password=a" />
</server>

The url attribute of the <replication> element defines a master database. As demonstrated above, a full URL has to be specified including user and password attributes. The slave server uses these details to connect to the master server in order to listen to updates. The updates are automatically applied on the slave database, keeping it synchronized with the master database.

The same ObjectDB server can manage different types of databases, including master databases, slave database (by using one or more <replication> elements) and also databases that are not part of any cluster.

The replicated databases on the slave server are automatically generated under a special root directory, $replication, under the server data root directory. Starting a new replication of an existing master database requires copying the existing master database to the slave side.

Connecting to the Database Cluster

The configuration above demonstrates a situation in which the master database is managed by a server on localhost:6000 and the slave database is managed by a server on localhost:6001.

In this case, the master database can be accessed ordinarily as follows:

EntityManagerFactory emf = Persistence.createEntityManagerFactory(
    "objectdb://localhost:6000/my.odb;user=a;password=a");

A slightly different URL is required in order to access the slave database:

EntityManagerFactory emf = Persistence.createEntityManagerFactory(
    "objectdb://localhost:6001//localhost:6000/my.odb;user=b;password=b");

The above URL specifies the location of the slave server on port 6001 as well as the location of the master server on port 6000. Notice that the specified user and password attributes should represent a user on the slave server rather than on the master server.

Finally, a composite URL can also be used:

EntityManagerFactory emf = Persistence.createEntityManagerFactory(
    "objectdb://localhost:6000/my.odb;user=a;password=a|" +
    "objectdb://localhost:6001//localhost:6000/my.odb;user=b;password=b"
);

A composite URL contains two or more database URLs separated by '|'. Usually, only the first URL (the master database in this example) is used. But when the first URL becomes unavailable the connection will automatically switch (temporarily) to the next available URL (i.e. in this example to the slave database) until the first URL becomes available again.