###

Berkeley DB Reference Guide:
  Berkeley DB Replication

# Building replicated applications

The simplest way to build a replicated Berkeley DB application is to first build (and debug!) the transactional version of the same application. Then, add a thin replication layer to the application. Highly available applications use the following additional four Berkeley DB methods: DB_ENV->rep_elect, DB_ENV->rep_process_message, DB_ENV->rep_start and DB_ENV->set_rep_transport:

DB_ENV->set_rep_transport
  The DB_ENV->set_rep_transport function configures the replication system's communications infrastructure.

DB_ENV->rep_start
  The DB_ENV->rep_start function configures (or reconfigures) an existing database environment to be a replication master or client.

DB_ENV->rep_process_message
  The DB_ENV->rep_process_message function is used to process incoming messages from other environments in the replication group. For clients, it is responsible for accepting log records and updating the local databases based on messages from the master. For both the master and the clients, it is responsible for handling administrative functions (for example, the protocol for dealing with lost messages), and permitting new clients to join an active replication group.

DB_ENV->rep_elect
  The DB_ENV->rep_elect function causes the replication group to elect a new master; it is called whenever contact with the master is lost.

To add replication to a Berkeley DB application, application initialization must be changed, and some new code, the application's communications infrastructure, must be written. The application initialization changes are relatively simple, but the communications infrastructure code is fairly complex.

During application initialization, the application must perform two additional tasks: first, it must provide Berkeley DB information about its communications infrastructure, and second, it must start the Berkeley DB replication system. Generally, a replicated application will do normal Berkeley DB recovery and configuration, exactly like any other transactional application. Then, once the database environment has been opened, it will call the DB_ENV->set_rep_transport function to configure Berkeley DB for replication, and then will call the DB_ENV->rep_start function to join or create the replication group. When calling DB_ENV->rep_start, the application has two choices: specifically configure the master for the replication group, or, alternatively, configure all group members as clients and then call an election, letting the clients select the master from among themselves. Either is correct, and the choice is entirely up to the application.

The result of calling DB_ENV->rep_start is usually the discovery of a master, or the declaration of the local environment as the master. If a master has not been discovered after a reasonable amount of time, the application should call DB_ENV->rep_elect to call for an election.

Databases are generally opened read-write on both clients and masters in order to simplify upgrading replication clients to be masters. (If databases are opened read-only on clients, and the client is then upgraded to be the master, the client would have to close and reopen all of its databases in order to support database update queries.) However, even though the database is opened read-write on the client, any attempt to update it will result in an error until the client is reconfigured as a master.

There are no additional interface calls required to shut down a database environment participating in a replication group. The application should shut down the environment in the usual manner, by calling the DB_ENV->close function.

Copyright Sleepycat Software