RavenDB supports replicating databases between two or more servers. Replication ensures all changes to documents (creates, updates, and deletes) on the source server (master) will be automatically mirrored to all destination servers (slaves). Replication is a good solution for both redundancy and scalability. By design, RavenDB’s support for replication is shipped as a separate bundle (or plugin) you must install and configure.

Replication Checklist

Before installing and configuring the RavenDB replication bundle, there are a few things you need to verify.

• Replication requires two or more instances of RavenDB are installed and running. (Note: For testing purposes, it is possible to have more than one instance of RavenDB running on the same computer.)
• Make sure the master server can communicate with each destination server over the TCP port RavenDB is configured to use. By default, RavenDB uses port 8080. This may require firewall configuration.
• If you are replicating a tenant database (any database other than the Default), make sure an equivalent tenant database exists on each of the destination servers. It is good practice to use a tenant database instead of the Default database.

Installing the Replication Bundle

1. On the master server, locate the folder where RavenDB Server is installed, and create a new folder named “Plugins” if it does not already exist.
2. In the “Bundles” folder included with the RavenDB download, copy the “Raven.Bundles.Replication” files to the “Plugins” folder created in Step 1.
3. Restart RavenDB

Configuring Replication Destinations

1. Open your browser and navigate to the RavenDB administration console (e.g. http://ravendb_1:8080)
2. Select the database you wish to replicate
3. Click on the Documents tab
4. Click on “Create a Document”
   
5. Name the document “Raven/Replication/Destinations”
6. Enter the following JSON, changing the name(s) of your destination server(s). This example shows two destination servers, but you can define one, two, three, or as many as you require.

   {
     "Destinations": [
       {
         "Url": "http://ravendb_2:8080/databases/mydb"
       },
       {
         "Url": "http://ravendb_3:8080/databases/mydb"
       }
     ]
   }

7. Click the “Save” icon. (Note: You may be prompted to enter your server credentials to save the document.)

You are done! As soon as you save the Raven/Replication/Destinations document, the master server will immediately contact the other server(s) and begin replicating documents.

Changing Destination Servers

Over time, you may need to add or remove destination servers. To do this, you’ll need to edit the existing Raven/Replication/Destinations document.

1. Open your browser and navigate to the RavenDB administration console.
2. Select the database to manage.
3. Click on the Documents tab.
4. Click “Edit Document By ID”.
5. For the Document ID, enter “Raven/Replication/Destinations” without quotes, and click OK.
6. Make changes to the list of destination servers, and click the Save icon.

Masters and Slaves

At this point, you now have a master -> slave configuration. Any changes made to the master server will be propagated to the other server(s). However, if you make any changes to documents on a slave server, those changes will not be reflected on other servers. Slave servers are effectively “read-only,” and this may be exactly what you want.

RavenDB supports master <-> master, or multiple master, configuration scenarios. Any changes to any of the master servers would be replicated to the other master (and slave) servers. This may be ideal if you wish to have servers located in different datacenters, and have clients connect to the server nearest to them. Another possible scenario is you want automatic failover from a primary server to a “hot spare”, and for any changes to the backup server to synchronize back to the primary once the failed primary comes back online.

To set up more than one master, simply configure a slave server the same way as the first master. You would install the replication bundle, restart RavenDB, and create the Raven/Replication/Destinations document listing all the destination servers, including the other master servers. Keep in mind, in multiple master configurations, there is the risk of conflicts if the same document is updated on more than one server before replication occurs. RavenDB Server and the RavenDB Client can resolve document conflicts in a variety of ways, but this is beyond the scope of this post.