Skip to content

John Bennett's blog

RavenDB replication – activating the replication bundle

Wednesday, January 2, 2013

Replication is one of many optional RavenDB features that is implemented as a “bundle”.  That is, it is code that is optionally active in the Raven server.  The Raven client knows how to read and interpret some system documents that configure replication, but that’s for a later post.  Here, I’m just talking about enabling replication on a Raven server.

In Raven 1.0, the replication bundle was a separate DLL that had to be deployed to the Plugins directory of the servers hosting each source and destination database. You activated replication by deploying Raven.Bundles.Replication.dll to that folder.  This was a pain.  There is no NuGet package that does this for you.  You have to download a build and manually copy the DLLs to the right place.

The story is much better in Raven 2.0.  The “built-in” bundles have been moved into Raven.Database.dll — the core server implementation — so they do not require separate deployment. However, there is still an opt-in step to enable each bundle, including replication.  Opt-in is required because the bundle makes changes to system documents as well as metadata stored in your documents.

When creating a database in the Studio, check the box to enable replication. This must be done for each database that will be either a source or a destination in a replication relationship.

As with all the built-in bundles, you must enable the replication bundle when you first create the database — before any documents have been created. Bundles are not designed to be activated or deactivated after documents exist. Doing so is unsupported and may lead to unpredictable results.

You do not have to configure any replication destinations on the “Setup Bundles” screen. Activating the bundle is the only requirement at the time you create a database. Additional configuration can take place at any point in the future.

If you create the database outside the Studio, for example with the EnsureDatabaseExists() method in the client API, you still need to enable replication as a separate step. Do so immediately after creating the database.

To enable the replication bundle manually, you modify a system document. The <system> database on a Raven Server contains a document for each database you create on that server. The document Id is Raven/Databases/MyDb, where MyDb is the database name.

The ActiveBundles property in that document is a semicolon-delimited string containing the names of the active built-in bundles. Add the value “Replication” to that string to activate the replication bundle.

It is possible to do this in code instead of manually.  Brnkly (a set of admin tools for Raven replication that I’ll get into soon) does this for you.  See the code. The important thing to remember with that code is that the DocumentStore Url must not include a database name and the DefaultDatabase must be empty or null.  The Brnkly code calls an extension method on Uri named GetServerRootUrl(), which ensures it is talking to the <system> database.

What does activating the replication bundle do?

Activating the replication bundle does not cause replication to start — you haven’t told Raven about any replication destinations. However, activating the bundle does have several effects:

  • Additional metadata is stored on every save of a document. This is why it is critical to activate replication before saving any documents. The metadata is used to detect replication conflicts. I’ll cover conflicts and this metadata in more detail in a future post. Just know that if you try to activate replication after you have data, you are very likely to have difficult-to-resolve conflicts.
  • The replication HTTP endpoints are enabled for the database, so that inbound replication from other servers can take place. (Remember: replication requests are always sent from source to destination.)  If the database in which you are activating the bundle is already configured as a replication destination, inbound replication will begin shortly after you activate the bundle.
  • A background task is created to handle outbound replication from this database. It will watch and wait, doing nothing until you have configured at least one replication destination.

Up next we’ll configuring a replication destination and look at the documents that control the process…