Configuring Database Replication

This section describes how to configure MarkLogic Server clusters for database replication. To get the most out of this section, first read Understanding Database Replication and Database Replication Quick Start to familiarize yourself with replication principles and basic configuration procedures.

To use the REST API to script database replication, see Scripting Database Replication Configuration in Script Administrative Tasks.

This section includes the following sections:

• Database Replication Security
• Avoid Replicating the App-Services Database
• Configuring Database Replication
• Connecting Primary and Replica Forests with Different Names
• Enabling, Disabling, Suspending, and Resuming Database Replication
• Deleting a Database Replication Configuration
• Decoupling the Local and Foreign Clusters
• Configuring App Servers on the Replica Cluster
• Changing the Foreign Bind Port
• TCP Tuning For High-Latency Environments

Database Replication Security

The admin role is required to configure and couple local and foreign clusters and to configure database replication.

When coupling clusters, you can configure SSL to encrypt the XDQP data passed between them. For details on configuring SSL, see Coupling Clusters in Administrate MarkLogic Server. If SSL is enabled for XDQP, then you must set the protocol to HTTPS in the procedures described in Coupling Clusters in Administrate MarkLogic Server.

Avoid Replicating the App-Services Database

We recommend that you do not set up database replication on the App-Services database. The App-Services database stores information used in Query Console and for other internal applications. So, it needs to be writable on all hosts. Otherwise, those applications might not work correctly.

Configuring Database Replication

Before you configure clusters for database replication, you must couple the clusters as described in Coupling Clusters in Administrate MarkLogic Server.

This section describes how to configure database replication on the cluster that hosts the primary database. Before starting this procedure, you must have identified all of the foreign clusters that you plan to replicate to by following the procedure described in Coupling Clusters in Administrate MarkLogic Server.

This section describes how to configure database replication from the primary cluster. You can also configure database replication on a replica cluster. But, if you are replicating to multiple replica clusters, then it is more convenient to do all of the configuration from the primary cluster.

Follow these steps for each replicated database and for each replica cluster:

1. On the bootstrap host in the primary cluster, navigate to the database to be replicated in the left menu tree, and select Database Replication:

   

2. Select the Configure tab and then select a replica cluster from the Foreign Cluster dropdown:

   

3. The Configure Database Replication page changes. For Local Database as, select master (primary). Select the database to be replicated to from the Foreign Database dropdown:

   

   Also set these values on the Configure Database Replication page:

   Database Replication Setting	Description
   Lag Limit	The replica cluster sends an acknowledgement to the primary cluster each time it receives a replicated journal frame. You can set a Lag Limit in your configuration that specifies that transactions on the primary will be stalled if the primary does not receive an acknowledgement from the replica within the number of seconds specified by the Lag Limit. By default, the Lag Limit is 15 seconds. For more information on Lag Limit, see Replication Lag.
   Connect Forests by Name	If the forest names are the same on the primary and replica clusters, then set Connect Forests by Name to true. If new forests of the same name are later added to the primary and replica databases, then they will be automatically configured for database replication. If you set Connect Forests by Name to false, then you must manually connect the primary forests on the local cluster to the replica forests on the foreign cluster as described in Connecting Primary and Replica Forests with Different Names.
   Foreign Admin Interface Protocol	The communication protocol to be used to connect to the foreign Admin App Server. Select https if SSL is enabled on the Admin App Server on the bootstrap host in the foreign cluster. Otherwise, select http.
   Foreign Admin Interface Port	If the Admin App Server for the bootstrap host on the foreign cluster uses a port other than 8001, then specify the port number.
   Host in Foreign Cluster	Select the name of a host on the foreign cluster from the dropdown.

4. When you have finished, click ok. The final Configure Database Replication page appears. Click ok to confirm the database replication configuration:

   

5. The Confirm to Add Foreign Replica page appears. Click ok:

   

6. The Summary tab appears with the database replication settings:

   

Connecting Primary and Replica Forests with Different Names

If you are replicating between databases that contain forests with different names, then you can manually connect primary to replica forests.

Follow these steps (with, for example, a database named Master on the primary cluster, a database named Replica on the replica cluster, and each database having unique forest names):

1. On the bootstrap host in the primary cluster, navigate to the primary database in the left menu tree, and select Database Replication:

   

2. In the Configure Database Replication, Step 1 page, select the foreign cluster that contains the replica database from the Foreign Cluster dropdown, and click ok:

   

3. In the Configure Database Replication, Step 2 page, select Replica from the Foreign Database dropdown:

   

4. Set Connect Forests by Name to false, then configure the other settings as described in Configuring Database Replication:

   

5. In the Connect Forests by Name table, use the dropdowns to connect the replica forests to the local primary forests. Click ok:

   

6. In the Confirm to Add Foreign Replica page, confirm the configuration, and click ok:

   

Enabling, Disabling, Suspending, and Resuming Database Replication

At the top of the database replication Summary page are buttons to enable, disable, suspend, and resume database replication and a button to repair the indexing information of the replica database:

The indexing information on the replica database can become different from that on the primary database because the replica is read-only and so does not reindex like the primary. This condition needs to be repaired so that queries return the same results from both databases.

Deleting a Database Replication Configuration

You can delete a database replication configuration from a bootstrap host on either the primary or the replica cluster. Follow these steps to delete a database replication configuration on the primary cluster:

1. On the bootstrap host in the primary cluster, navigate to the primary database in the left menu tree, and select Database Replication:

   

2. In the Foreign Replicas for Database Master (Primary) section of the Summary page, click Delete:

   

3. In the Delete Database Replication page, if SSL is enabled on the replica cluster's bootstrap host's Admin App Server, select https from the Foreign Admin Interface Protocol dropdown. Click ok:

   

4. In the Confirm to Delete Database Replication page, click ok:

   

Decoupling the Local and Foreign Clusters

To decouple clusters, see Decoupling Clusters in Administrate MarkLogic Server.

Configuring App Servers on the Replica Cluster

As described in Reducing Blocking with Multi-Version Concurrency Control in Develop Server-Side Applications, setting multiversion concurrency control to nonblocking on an app server minimizes transaction blocking, which is useful if the app server uses a replica database that significantly lags its primary database.

We recommended that, at a minimum, you set multiversion concurrency control to nonblocking on the Admin App Server because the Security database is typically not updated frequently. The nonblocking multiversion concurrency control option minimizes transaction blocking, but queries potentially see a less timely view of the database. So, you must weigh these two factors when determining whether to set this option on other app servers on your replica cluster.

Changing the Foreign Bind Port

As described in Inter-cluster Communication, communication between clusters is done using the intra-cluster XDQP protocol on the foreign bind port. By default, the foreign bind port is port 7998. This section describes how to change the foreign bind port.

Follow these steps for each host in the cluster that is involved in inter-cluster replication:

1. Select a host in the local cluster under Hosts in the left menu tree:

   

2. In the Host Configuration page, change the port number in the foreign bind port field, and click ok:

   

TCP Tuning For High-Latency Environments

On Linux systems, if you have configured database replication where there is high-latency between the primary and the replica environments (for example, if your primary is in San Francisco and your replica is in Tokyo), then you might need to tune the Linux TCP settings to increase throughput. These are examples of the tuned Linux TCP setting (these settings are tuned with values greater than the typical defaults):

# sysctl -w net.core.rmem_max=8388608
net.core.rmem_max = 8388608
# sysctl -w net.core.wmem_max=8388608
net.core.wmem_max = 8388608
# sysctl -w net.ipv4.tcp_mem='8388608 8388608 8388608'
net.ipv4.tcp_mem = 8388608 8388608 8388608
# sysctl -w net.ipv4.tcp_rmem='4096 87380 8388608'
net.ipv4.tcp_rmem = 4096 87380 8388608
# sysctl -w net.ipv4.tcp_wmem='4096 87380 8388608'
net.ipv4.tcp_wmem = 4096 87380 8388608
# sysctl -w net.ipv4.route.flush=1
net.ipv4.route.flush = 1 

To see your current TCP settings, run this Unix command:

# sysctl -a | grep mem

The preceding setting changes the running system, but it does not survive a reboot. So, once you have tuned your system to your satisfaction, you need to add these settings to your startup environment to persist them through system reboots.

For details on your TCP settings, see your operating system documentation. If you have questions about how these operating system parameters might behave with your MarkLogic environment and you have an active maintenance contract, then you can contact MarkLogic Technical Support for help.