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. The database replication Summary page appears.

2. Select the Configure tab. Configure Database Replication, Page 1 appears with your chosen database unchangeable in the Local Database field.

3. Select a replica cluster from the Foreign Cluster dropdown, and click OK. Configure Database Replication, Page 2 appears.

4. For Local Database As, select master (primary).

5. From the Foreign Database dropdown, select the replica database for this primary.

6. Set the rest of the values according to your needs:

   Database Replication Setting	Description
   Lag Limit	Set how long the primary cluster should wait for its replica cluster to acknowledge receipt of a replicated journal frame before the primary stalls replication transactions. Default:15 seconds. Range: 0-1,000,000,000. See Replication Lag.
   Queue Size	Set the maximum number of journal frames that can be buffered for replication. Default: 10. Range: 1-1000.
   Replication Enabled	Set to true to keep database replication enabled after restart or failover. Set to false to keep database replication disabled after restart or failover. Default: true.
   Connect Forests by Name	Set to true to automatically match current primary forests to replica forests of the same name, to automatically match any future primary forests to replicas of the same name, and to automatically configure these future forests for database replication. Set to false to manually match current and future primary forests to their replicas and to manually configure future forests for database replication. This setting is required if your primary forests have different names than their replicas. See Connecting Primary and Replica Forests with Different Names. Default: true.
   Foreign Admin Interface Protocol	Select from the dropdown the communication protocol for connecting to the foreign Admin App Server. Select https if SSL is enabled on the foreign cluster Admin App Server bootstrap host. Select http otherwise. Default: http.
   Foreign Admin Interface Port	Set the foreign cluster Admin App Server bootstrap host port number. Default: 8001.
   Host in Foreign Cluster	Select from the dropdown the host on the foreign cluster to be the bootstrap host.

7. When you have finished setting these values, click OK. The final Configure Database Replication page appears, summarizing the data that you have entered. If you have set Connect Forests by Name to false, then you can manually map primary to replica forests.

8. Click OK to confirm the database replication configuration. The Database Replication - Validated (Local) confirmation page appears.

9. Click OK. The Sign in page for the foreign cluster appears.

10. Sign in to the foreign cluster. The Confirm to Add Foreign Replica confirmation page appears.

11. Click OK. The Summary tab appears with the summary of your 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.

1. Follow the steps in Configuring Database Replication, setting Connect Forests By Name to false and setting any other values as desired. When the final Configure Database Replication page appears, the forest table has dropdowns in the Replica Forest column.

2. Use the dropdowns to choose a Replica Forest for each Master Forest (primary forest).

3. When each Master Forest (primary forest) has a unique Replica Forest, click OK, then continue the rest of the steps in Configuring Database Replication until the Summary tab appears.

Enabling, Disabling, Suspending, and Resuming Database Replication

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

More details about the button functions are in this table:

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. The database replication Summary page appears.

2. In the Foreign Replicas for Database (database) section of the Summary page, click Delete in the Delete column for the Foreign Cluster to delete. The Delete Database Replication page appears.

3. If SSL is enabled on the replica cluster's bootstrap host's Admin App Server, select https from the Foreign Admin Interface Protocol dropdown.

4. Click OK. The Sign in page for the foreign cluster appears.

5. Sign in to the foreign cluster. The Confirm to Delete Database Replication page appears.

6. Click OK. The Summary tab appears.

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 recommend 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. The Host Configuration page appears.

2. Change the Foreign Bind Port to your desired value, and click OK. The host restarts.

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.