1<!--$Id: mastersync.so,v 1.14 2008/02/29 18:28:33 sue Exp $--> 2<!--Copyright (c) 1997,2008 Oracle. All rights reserved.--> 3<!--See the file LICENSE for redistribution information.--> 4<html> 5<head> 6<title>Berkeley DB Reference Guide: Synchronizing with a master</title> 7<meta name="description" content="Berkeley DB: An embedded database programmatic toolkit."> 8<meta name="keywords" content="embedded,database,programmatic,toolkit,btree,hash,hashing,transaction,transactions,locking,logging,access method,access methods,Java,C,C++"> 9</head> 10<body bgcolor=white> 11<table width="100%"><tr valign=top> 12<td><b><dl><dt>Berkeley DB Reference Guide:<dd>Berkeley DB Replication</dl></b></td> 13<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> 14</td></tr></table> 15<p align=center><b>Synchronizing with a master</b></p> 16<p>When a client detects a new replication group master, the client must 17synchronize with the new master before the client can process new 18database changes. Synchronizing is a heavyweight operation which can 19place a burden on both the client and the master. There are several 20controls an application can use to reduce the synchronization burden.</p> 21<b>Delaying client synchronization</b> 22<p>When a replication group has a new master, either as specified by the 23application or as a result of winning an election, all clients in the 24replication group must synchronize with the new master. This can 25strain the resources of the new master since a large number of clients 26may be attempting to communicate with and transfer records from the 27master. Client applications wanting to delay client synchronization 28should call the <a href="../../api_c/rep_config.html">DB_ENV->rep_set_config</a> method with the 29<a href="../../api_c/rep_config.html#DB_REP_CONF_DELAYCLIENT">DB_REP_CONF_DELAYCLIENT</a> flag. The application will be 30notified of the establishment of the new master as usual, but the 31client will not proceed to synchronize with the new master.</p> 32<p>Applications learn of a new master via the 33<a href="../../api_c/env_event_notify.html#DB_EVENT_REP_NEWMASTER">DB_EVENT_REP_NEWMASTER</a> event.</p> 34<p>Client applications choosing to delay synchronization in this manner are 35responsible for synchronizing the client environment at some future time 36using the <a href="../../api_c/rep_sync.html">DB_ENV->rep_sync</a> method.</p> 37<b>Client-to-client synchronization</b> 38<p>Instead of synchronizing with the new master, it is sometimes possible 39for a client to synchronize with another client. Berkeley DB initiates 40synchronization at the client by sending a request message via the 41transport call-back function of the communication infrastructure. The 42message is destined for the master site, but is also marked with a 43<a href="../../api_c/rep_transport.html#DB_REP_ANYWHERE">DB_REP_ANYWHERE</a> flag. The application may choose to send such 44a request to another client, or to ignore the flag, sending it to its 45indicated destination.</p> 46<p>Furthermore, when the other client receives such a request it may be 47unable to satisfy it. In this case it will reply to the requesting 48client, telling it that it is unable to provide the requested 49information. The requesting client will then re-issue the request. 50Additionally, if the original request never reaches the other client, 51the requesting client will again re-issue the request. In either of 52these cases the message will be marked with the <a href="../../api_c/rep_transport.html#DB_REP_REREQUEST">DB_REP_REREQUEST</a> 53flag. The application may continue trying to find another client to 54service the request, or it may give up and simply send it to the master 55(that is, the environment ID explicitly specified to the transport 56function).</p> 57<p>Applications written to the Base replication API have complete freedom 58in choosing where to send these <a href="../../api_c/rep_transport.html#DB_REP_ANYWHERE">DB_REP_ANYWHERE</a> requests, and 59in deciding how to handle <a href="../../api_c/rep_transport.html#DB_REP_REREQUEST">DB_REP_REREQUEST</a>.</p> 60<p>Replication Manager allows an application to designate one remote site 61(called its "peer") to receive client-to-client requests, via the 62flags parameter to the <a href="../../api_c/repmgr_remote_site.html">DB_ENV->repmgr_add_remote_site</a> method. Replication 63Manager will always first try to send requests marked with the 64<a href="../../api_c/rep_transport.html#DB_REP_ANYWHERE">DB_REP_ANYWHERE</a> flag to its peer, if available. However, it 65will always send a <a href="../../api_c/rep_transport.html#DB_REP_REREQUEST">DB_REP_REREQUEST</a> to the master site.</p> 66<p>The delayed synchronization and client-to-client synchronization 67features allow applications to do load balancing within replication 68groups. For example, consider a replication group with 5 sites, A, B, 69C, D and E. Site E just crashed, and site A was elected master. Sites 70C and D have been configured for delayed synchronization. When site B 71is notified that site A is a new master, it immediately synchronizes. 72When B finishes synchronizing with the master, the application calls the 73<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. 74Sites C and D (and E, when it has finished rebooting) can send their 75requests to site B, and B then bears the brunt of the work and 76network traffic for synchronization, making master site A available to 77handle the normal application load and any write requests paused by 78the election.</p> 79<b>Blocked client operations</b> 80<p>Clients in the process of synchronizing with the master block access to 81Berkeley DB operations. By default, most Berkeley DB methods will block until 82client synchronization is complete, and then the method call proceeds.</p> 83<p>Client applications which cannot wait and would prefer an immediate 84error return instead of blocking, should call the 85<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 86configuration causes <a href="../../api_c/db_class.html">DB</a> method calls to immediately return a 87<a href="../../api_c/db_put.html#DB_REP_LOCKOUT">DB_REP_LOCKOUT</a> error instead of blocking, if the client is 88currently synchronizing with the master.</p> 89<b>Clients too far out-of-date to synchronize</b> 90<p>Clients attempting to synchronize with the master may discover that 91synchronization is not possible because the client no longer has any 92overlapping information with the master site. By default, the master and 93client automatically detect this state and perform an internal initialization 94of the client. Because internal initialization requires transfer of 95entire databases to the client, it can take a relatively long period of 96time and may require database handles to be reopened in the client 97applications.</p> 98<p>Client applications which cannot wait or would prefer 99to do a hot backup instead of performing internal initialization, should 100call 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> 101flag. This configuration flag causes Berkeley DB to return 102<a href="../../api_c/rep_message.html#DB_REP_JOIN_FAILURE">DB_REP_JOIN_FAILURE</a> to the application instead of performing 103internal initialization.</p> 104<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> 105</td></tr></table> 106<p><font size=1>Copyright (c) 1996,2008 Oracle. All rights reserved.</font> 107</body> 108</html> 109