Chapter 1. Introduction

Table of Contents

Replication Environments
Replication Databases
Communications Layer
Selecting a Master
Replication Benefits
Replication Mechanisms
Replication Manager Overview
Write Forwarding Overview
Replication Base API Overview
Holding Elections
Influencing Elections
Winning Elections
Switching Masters
Permanent Message Handling
When Not to Manage Permanent Messages
Managing Permanent Messages
Implementing Permanent Message Handling
Event Handling

This book provides a thorough introduction and discussion on replication as used with Berkeley DB (DB). It begins by offering a general overview to replication and the benefits it provides. It also describes the APIs that you use to implement replication, and it describes architecturally the things that you need to do to your application code in order to use the replication APIs. Finally, it discusses the differences in backup and restore strategies that you might pursue when using replication, especially where it comes to log file removal.

You should understand the concepts from the Berkeley DB Getting Started with Transaction Processing guide before reading this book.


The DB replication APIs allow you to distribute your database write operations (performed on a read-write master) to one or more read-only replicas. For this reason, DB's replication implementation is said to be a single master, multiple replica replication strategy.

Note that your database write operations can occur only on the master; any attempt to write to a replica results in an error being returned to the DB API used to perform the write.

A single replication master and all of its replicas are referred to as a replication group. While all members of the replication group can reside on the same machine, usually each replication participant is placed on a separate physical machine somewhere on the network.

Note that all replication applications must first be transactional applications. The data that the master transmits to its replicas are log records that are generated as records are updated. Upon transactional commit, the master transmits a transaction record which tells the replicas to commit the records they previously received from the master. In order for all of this to work, your replicated application must also be a transactional application. For this reason, it is recommended that you write and debug your DB application as a stand-alone transactional application before introducing the replication layer to your code.

Replication Environments

The most important requirement for a replication participant is that it must use a unique Berkeley DB database environment independent of all other replication participants. So while multiple replication participants can reside on the same physical machine, no two such participants can share the same environment home directory.

For this reason, technically replication occurs between unique database environments. So in the strictest sense, a replication group consists of a master environment and one or more replica environments. However, the reality is that for production code, each such environment will usually be located on its own unique machine. Consequently, this manual sometimes talks about replication sites, meaning the unique combination of environment home directory, host and port that a specific replication application is using.

There is no DB-specified limit to the number of environments which can participate in a replication group. The only limitation here is one of resources — network bandwidth, for example.

(Note, however, that the Replication Manager does place a limit on the number of environments you can use. See Replication Manager Overview for details.)

Also, DB's replication implementation requires all participating environments to be assigned IDs that are locally unique to the given environment. Depending on the replication APIs that you choose to use, you may or may not need to manage this particular detail.

For detailed information on database environments, see the Berkeley DB Getting Started with Transaction Processing guide. For more information on environment IDs, see the Berkeley DB Programmer's Reference Guide.

Replication Databases

DB's databases are managed and used in exactly the same way as if you were writing a non-replicated application, with a couple of caveats. First, the databases maintained in a replicated environment must reside either in the ENV_HOME directory, or in the directory identified by the DB_ENV->add_data_dir() method. Unlike non-replication applications, you cannot place your databases in a subdirectory below these locations. You should also not use full path names for your databases or environments as these are likely to break when they are replicated to other machines.

Communications Layer

In order to transmit database writes to the replication replicas, DB requires a communications layer. DB is agnostic as to what this layer should look like. The only requirement is that it be capable of passing two opaque data objects and an environment ID from the master to its replicas without corruption.

Because replicas are usually placed on different machines on the network, the communications layer is usually some kind of a network-aware implementation. Beyond that, its implementation details are largely up to you. It could use TCP/IP sockets, for example, or it could use raw sockets if they perform better for your particular application.

Note that you may not have to write your own communications layer. DB provides a Replication Manager that includes a fully-functional TCP/IP-based communications layer, which uses IPv6 whenever possible but also supports IPv4. See Replication Mechanisms for more information.

See the Berkeley DB Programmer's Reference Guide for a description of how to write your own custom replication communications layer.

Selecting a Master

Every replication group is allowed one and only one master environment. Usually masters are selected by holding an election, although it is possible to turn elections off and manually select masters (this is not recommended for most replicated applications).

When elections are being used, they are performed by the underlying Berkeley DB replication code so you have to do very little to implement them.

When holding an election, replicas "vote" on who should be the master. Among replicas participating in the election, the one with the most up-to-date set of log records will win the election. Note that it's possible for there to be a tie. When this occurs, priorities are used to select the master. See Holding Elections for details.

For more information on holding and managing elections, see Holding Elections.