Applications which use the Replication Manager support generally call the following Berkeley DB methods. The general pattern is to call various methods to configure Replication Manager, and then start it by calling DB_ENV->repmgr_start(). Once this initialization is complete, the application rarely needs to call any of these methods. (A prime example of an exception to this rule would be the DB_ENV->rep_sync() method, if the application is Delaying client synchronization.)
The DB_SITE handle is used to configure a site that belongs to the replication group. You can obtain a DB_SITE handle by calling the DB_ENV->repmgr_site() method. When you do this, you provide the TCP/IP host name and port that the replication site uses for incoming connections.
Once you have the DB_SITE handle, you use the
DB_SITE->set_config() method to configure the handle. One of
the things you can configure about the handle is whether it
is the local site (using the DB_LOCAL_SITE
parameter). You must configure one and only one DB_SITE handle
to be a local site before you start replication.
You can also optionally configure DB_SITE handles for remote sites to help Replication Manager startup more efficiently. Note that it is usually not necessary for each site in the replication group initially to know about all other sites in the group. Sites can discover each other dynamically, as described in Connecting to a new site.
Once you have configured your DB_SITE handles, you start replication using DB_ENV->repmgr_start().
When you are shutting down your application, you must use the DB_SITE->close() method to close all your open DB_SITE handles before you close your environment handles.
The DB_ENV->repmgr_set_ack_policy() method configures the acknowledgement policy to be used in the replication group, in other words, the behavior of the master with respect to acknowledgements for "permanent" messages, which implements the application's requirements for Transactional guarantees. The current implementation requires all sites in the replication group to configure the same acknowledgement policy.
The DB_ENV->rep_set_priority() method configures the local site's priority for the purpose of elections.
This method optionally configures various timeout values. Otherwise default timeout values as specified in DB_ENV->rep_set_timeout() are used. In particular, Replication Manager client sites can be configured to monitor the health of the TCP/IP connection to the master site using heartbeat messages. If the client receives no messages from the master for a certain amount of time, it considers the connection to be broken, and calls for an election to choose a new master. Heartbeat messages also help clients request missing master changes in the absence of master activity.
Once configured and started, Replication Manager does virtually all of its work in the background, usually without the need for any direct communication with the application. However, occasionally events occur which the application may be interested in knowing about. The application can request notification of these events by calling the DB_ENV->set_event_notify() method.
The DB_ENV->repmgr_start() method starts the replication system. It opens the listening TCP/IP socket and creates all the background processing threads that will be needed.
In addition to the methods previously described, Replication Manager applications may also call the following methods, as needed: DB_ENV->rep_set_config(), DB_ENV->rep_set_limit(), DB_ENV->rep_set_request(), DB_ENV->rep_sync() and DB_ENV->rep_stat().
Finally, Replication Manager applications can also make use of the Replication Manager's message channels. This allows the various sites in the replication group to pass messages that are tailored to the application's requirements. For more information, see Using Replication Manager message channels.