<!--$Id: mastersync.so,v 1.14 2008/02/29 18:28:33 sue Exp $--> <!--Copyright (c) 1997,2008 Oracle. All rights reserved.--> <!--See the file LICENSE for redistribution information.--> <html> <head> <title>Berkeley DB Reference Guide: Synchronizing with a master</title> <meta name="description" content="Berkeley DB: An embedded database programmatic toolkit."> <meta name="keywords" content="embedded,database,programmatic,toolkit,btree,hash,hashing,transaction,transactions,locking,logging,access method,access methods,Java,C,C++"> </head> <body bgcolor=white> <table width="100%"><tr valign=top> <td><b><dl><dt>Berkeley DB Reference Guide:<dd>Berkeley DB Replication</dl></b></td> <td align=right><a href="../rep/elect.html"><img src="../../images/prev.gif" alt="Prev"></a><a href="../toc.html"><img src="../../images/ref.gif" alt="Ref"></a><a href="../rep/init.html"><img src="../../images/next.gif" alt="Next"></a> </td></tr></table> <p align=center><b>Synchronizing with a master</b></p> <p>When a client detects a new replication group master, the client must synchronize with the new master before the client can process new database changes. Synchronizing is a heavyweight operation which can place a burden on both the client and the master. There are several controls an application can use to reduce the synchronization burden.</p> <b>Delaying client synchronization</b> <p>When a replication group has a new master, either as specified by the application or as a result of winning an election, all clients in the replication group must synchronize with the new master. This can strain the resources of the new master since a large number of clients may be attempting to communicate with and transfer records from the master. Client applications wanting to delay client synchronization should call the <a href="../../api_c/rep_config.html">DB_ENV->rep_set_config</a> method with the <a href="../../api_c/rep_config.html#DB_REP_CONF_DELAYCLIENT">DB_REP_CONF_DELAYCLIENT</a> flag. The application will be notified of the establishment of the new master as usual, but the client will not proceed to synchronize with the new master.</p> <p>Applications learn of a new master via the <a href="../../api_c/env_event_notify.html#DB_EVENT_REP_NEWMASTER">DB_EVENT_REP_NEWMASTER</a> event.</p> <p>Client applications choosing to delay synchronization in this manner are responsible for synchronizing the client environment at some future time using the <a href="../../api_c/rep_sync.html">DB_ENV->rep_sync</a> method.</p> <b>Client-to-client synchronization</b> <p>Instead of synchronizing with the new master, it is sometimes possible for a client to synchronize with another client. Berkeley DB initiates synchronization at the client by sending a request message via the transport call-back function of the communication infrastructure. The message is destined for the master site, but is also marked with a <a href="../../api_c/rep_transport.html#DB_REP_ANYWHERE">DB_REP_ANYWHERE</a> flag. The application may choose to send such a request to another client, or to ignore the flag, sending it to its indicated destination.</p> <p>Furthermore, when the other client receives such a request it may be unable to satisfy it. In this case it will reply to the requesting client, telling it that it is unable to provide the requested information. The requesting client will then re-issue the request. Additionally, if the original request never reaches the other client, the requesting client will again re-issue the request. In either of these cases the message will be marked with the <a href="../../api_c/rep_transport.html#DB_REP_REREQUEST">DB_REP_REREQUEST</a> flag. The application may continue trying to find another client to service the request, or it may give up and simply send it to the master (that is, the environment ID explicitly specified to the transport function).</p> <p>Applications written to the Base replication API have complete freedom in choosing where to send these <a href="../../api_c/rep_transport.html#DB_REP_ANYWHERE">DB_REP_ANYWHERE</a> requests, and in deciding how to handle <a href="../../api_c/rep_transport.html#DB_REP_REREQUEST">DB_REP_REREQUEST</a>.</p> <p>Replication Manager allows an application to designate one remote site (called its "peer") to receive client-to-client requests, via the flags parameter to the <a href="../../api_c/repmgr_remote_site.html">DB_ENV->repmgr_add_remote_site</a> method. Replication Manager will always first try to send requests marked with the <a href="../../api_c/rep_transport.html#DB_REP_ANYWHERE">DB_REP_ANYWHERE</a> flag to its peer, if available. However, it will always send a <a href="../../api_c/rep_transport.html#DB_REP_REREQUEST">DB_REP_REREQUEST</a> to the master site.</p> <p>The delayed synchronization and client-to-client synchronization features allow applications to do load balancing within replication groups. For example, consider a replication group with 5 sites, A, B, C, D and E. Site E just crashed, and site A was elected master. Sites C and D have been configured for delayed synchronization. When site B is notified that site A is a new master, it immediately synchronizes. When B finishes synchronizing with the master, the application calls the <a href="../../api_c/rep_sync.html">DB_ENV->rep_sync</a> method on sites C and D to cause them to synchronize as well. Sites C and D (and E, when it has finished rebooting) can send their requests to site B, and B then bears the brunt of the work and network traffic for synchronization, making master site A available to handle the normal application load and any write requests paused by the election.</p> <b>Blocked client operations</b> <p>Clients in the process of synchronizing with the master block access to Berkeley DB operations. By default, most Berkeley DB methods will block until client synchronization is complete, and then the method call proceeds.</p> <p>Client applications which cannot wait and would prefer an immediate error return instead of blocking, should call the <a href="../../api_c/rep_config.html">DB_ENV->rep_set_config</a> method with the <a href="../../api_c/rep_config.html#DB_REP_CONF_NOWAIT">DB_REP_CONF_NOWAIT</a> flag. This configuration causes <a href="../../api_c/db_class.html">DB</a> method calls to immediately return a <a href="../../api_c/db_put.html#DB_REP_LOCKOUT">DB_REP_LOCKOUT</a> error instead of blocking, if the client is currently synchronizing with the master.</p> <b>Clients too far out-of-date to synchronize</b> <p>Clients attempting to synchronize with the master may discover that synchronization is not possible because the client no longer has any overlapping information with the master site. By default, the master and client automatically detect this state and perform an internal initialization of the client. Because internal initialization requires transfer of entire databases to the client, it can take a relatively long period of time and may require database handles to be reopened in the client applications.</p> <p>Client applications which cannot wait or would prefer to do a hot backup instead of performing internal initialization, should call the <a href="../../api_c/rep_config.html">DB_ENV->rep_set_config</a> method with the <a href="../../api_c/rep_config.html#DB_REP_CONF_NOAUTOINIT">DB_REP_CONF_NOAUTOINIT</a> flag. This configuration flag causes Berkeley DB to return <a href="../../api_c/rep_message.html#DB_REP_JOIN_FAILURE">DB_REP_JOIN_FAILURE</a> to the application instead of performing internal initialization.</p> <table width="100%"><tr><td><br></td><td align=right><a href="../rep/elect.html"><img src="../../images/prev.gif" alt="Prev"></a><a href="../toc.html"><img src="../../images/ref.gif" alt="Ref"></a><a href="../rep/init.html"><img src="../../images/next.gif" alt="Next"></a> </td></tr></table> <p><font size=1>Copyright (c) 1996,2008 Oracle. All rights reserved.</font> </body> </html>