1<?xml version="1.0" encoding="UTF-8" standalone="no"?> 2<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"> 3<html xmlns="http://www.w3.org/1999/xhtml"> 4 <head> 5 <meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /> 6 <title>Master Leases</title> 7 <link rel="stylesheet" href="gettingStarted.css" type="text/css" /> 8 <meta name="generator" content="DocBook XSL Stylesheets V1.73.2" /> 9 <link rel="start" href="index.html" title="Berkeley DB Programmer's Reference Guide" /> 10 <link rel="up" href="rep.html" title="Chapter 12. Berkeley DB Replication" /> 11 <link rel="prev" href="rep_trans.html" title="Transactional guarantees" /> 12 <link rel="next" href="rep_clock_skew.html" title="Clock Skew" /> 13 </head> 14 <body> 15 <div class="navheader"> 16 <table width="100%" summary="Navigation header"> 17 <tr> 18 <th colspan="3" align="center">Master Leases</th> 19 </tr> 20 <tr> 21 <td width="20%" align="left"><a accesskey="p" href="rep_trans.html">Prev</a> </td> 22 <th width="60%" align="center">Chapter 12. 23 Berkeley DB Replication 24 </th> 25 <td width="20%" align="right"> <a accesskey="n" href="rep_clock_skew.html">Next</a></td> 26 </tr> 27 </table> 28 <hr /> 29 </div> 30 <div class="sect1" lang="en" xml:lang="en"> 31 <div class="titlepage"> 32 <div> 33 <div> 34 <h2 class="title" style="clear: both"><a id="rep_lease"></a>Master Leases</h2> 35 </div> 36 </div> 37 </div> 38 <p>Some applications have strict requirements about the consistency 39of data read on a master site. Berkeley DB provides a mechanism 40called master leases to provide such consistency. 41Without master leases, it is sometimes possible for 42Berkeley DB to return old data to an application when newer data is 43available due to unfortunate scheduling as illustrated below:</p> 44 <div class="orderedlist"> 45 <ol type="1"> 46 <li><span class="bold"><strong>Application on master site</strong></span>: Read data item 47<span class="emphasis"><em>foo</em></span> via Berkeley DB <a href="../api_reference/C/dbget.html" class="olink">DB->get()</a> or <a href="../api_reference/C/dbcget.html" class="olink">DBC->get()</a> call.</li> 48 <li><span class="bold"><strong>Application on master site</strong></span>: sleep, get descheduled, etc.</li> 49 <li><span class="bold"><strong>System</strong></span>: Master changes role, becomes a client.</li> 50 <li><span class="bold"><strong>System</strong></span>: New site is elected master.</li> 51 <li><span class="bold"><strong>System</strong></span>: New master modifies data item <span class="emphasis"><em>foo</em></span>.</li> 52 <li><span class="bold"><strong>Application</strong></span>: Berkeley DB returns old data for <span class="emphasis"><em>foo</em></span> 53to application.</li> 54 </ol> 55 </div> 56 <p>By using master leases, Berkeley DB can provide guarantees about the 57consistency of data read on a master site. The master site 58can be considered a recognized authority for the data and 59consequently can provide authoritative reads. Clients grant master 60leases to a master site. By doing so, clients acknowledge 61the right of that site to retain the role of master 62for a period of time. 63During that period of time, clients cannot elect a new 64master, become master, nor grant their lease to another site.</p> 65 <p>By holding a collection of granted leases, a master site can 66guarantee to the application that the data returned is the 67current, authoritative value. As a master performs operations, 68it continually requests updated grants from the clients. 69When a read operation is required, the master guarantees 70that it holds a valid collection of lease grants from clients 71before returning data to the application. By holding leases, 72Berkeley DB provides several guarantees to the application:</p> 73 <div class="orderedlist"> 74 <ol type="1"> 75 <li>Authoritative reads: A guarantee that the data being read by the 76application is the current value.</li> 77 <li>Durability from rollback: A guarantee that the data being written or read by the 78application is permanent across a majority of client sites and will 79never be rolled back. 80<p>The rollback guarantee also depends on the <a href="../api_reference/C/envset_flags.html#envset_flags_DB_TXN_NOSYNC" class="olink">DB_TXN_NOSYNC</a> flag. 81The guarantee is effective as long as there isn't total 82replication group failure while clients have granted leases 83but are holding the updates in their cache. 84The application must weigh the performance impact of synchronous 85transactions against the risk of total replication group failure. 86If clients grant a lease while holding updated data in cache, 87and total failure occurs, then the data is no longer present 88on the clients and rollback can occur if the master also crashes.</p><p>The guarantee that data will not be rolled back applies only 89to data successfully committed on a master. 90Data read on a client, or read while ignoring leases 91can be rolled back.</p></li> 92 <li>Freshness: A guarantee that the data being read by the application 93on the <span class="emphasis"><em>master</em></span> is up-to-date and has not been 94modified or removed during the read. 95<p>The read authority is only on the master. Read operations on a client 96always ignore leases and consequently, these operations can return stale data.</p></li> 97 <li>Master viability: A guarantee that a current master with valid 98leases cannot encounter a duplicate master situation. 99<p>Leases remove the possibility of a duplicate master situation that 100forces the current master to downgrade to a client. However, it is 101still possible that old masters with expired leases can discover a later 102master and return <a href="../api_reference/C/repmessage.html#repmsg_DB_REP_DUPMASTER" class="olink">DB_REP_DUPMASTER</a> to the application.</p></li> 103 </ol> 104 </div> 105 <p>There are several requirements of the application using leases:</p> 106 <div class="orderedlist"> 107 <ol type="1"> 108 <li>Replication Manager applications must configure a majority (or larger) 109acknowledgement policy via the <a href="../api_reference/C/repmgrset_ack_policy.html" class="olink">DB_ENV->repmgr_set_ack_policy()</a> method. Base API 110applications must implement and enforce such a policy on their own.</li> 111 <li>Base API applications must return an error from the send callback function when 112the majority acknowledgement policy is not met for permanent records 113marked with <a href="../api_reference/C/reptransport.html#transport_DB_REP_PERMANENT" class="olink">DB_REP_PERMANENT</a>. Note that the Replication Manager 114automatically fulfills this requirement.</li> 115 <li>Applications must set the number of sites in the group using the 116<a href="../api_reference/C/repnsites.html" class="olink">DB_ENV->rep_set_nsites()</a> method before starting replication and cannot 117change it during operation.</li> 118 <li>Using leases in a replication group is all or none. Behavior is 119undefined when some sites configure leases and others do not. 120Use the <a href="../api_reference/C/repconfig.html" class="olink">DB_ENV->rep_set_config()</a> method to turn on leases.</li> 121 <li>The configured lease timeout value must be the same on all sites 122in a replication group, set via the <a href="../api_reference/C/repset_timeout.html" class="olink">DB_ENV->rep_set_timeout()</a> method.</li> 123 <li>The configured clock_scale_factor value must be the same on all sites 124in a replication group. This value defaults to no skew, but can 125be set via the <a href="../api_reference/C/repclockskew.html" class="olink">DB_ENV->rep_set_clockskew()</a> method.</li> 126 <li>Applications that care about read guarantees must perform all read 127operations on the master. Reading on a client does not guarantee 128freshness.</li> 129 <li>The application must use elections to choose a master site. It must 130never simply declare a master without having won an election (as is 131allowed without Master Leases).</li> 132 </ol> 133 </div> 134 <p>Master leases are based on timeouts. Berkeley DB assumes that time 135always runs forward. Users who change the system clock on 136either client or master sites when leases are in use void all 137guarantees and can get undefined behavior. See the 138<a href="../api_reference/C/repset_timeout.html" class="olink">DB_ENV->rep_set_timeout()</a> method for more information.</p> 139 <p>Read operations on a master that should not be subject to 140leases can use the <a href="../api_reference/C/dbget.html#get_DB_IGNORE_LEASE" class="olink">DB_IGNORE_LEASE</a> flag to the 141<a href="../api_reference/C/dbget.html" class="olink">DB->get()</a> method. Read operations on a client always imply leases are ignored.</p> 142 <p>Clients are forbidden from participating in elections while 143they have an outstanding lease granted to a master. 144Therefore, if the <a href="../api_reference/C/repelect.html" class="olink">DB_ENV->rep_elect()</a> method is called, then Berkeley DB will 145block, waiting until its lease grant expires before participating in 146any election. While it waits, the client attempts to 147contact the current master. If the client finds a current 148master, then it returns from the <a href="../api_reference/C/repelect.html" class="olink">DB_ENV->rep_elect()</a> method. 149When leases are configured and the 150lease has never yet been granted (on start-up), clients 151must wait a full lease timeout before participating in 152an election.</p> 153 </div> 154 <div class="navfooter"> 155 <hr /> 156 <table width="100%" summary="Navigation footer"> 157 <tr> 158 <td width="40%" align="left"><a accesskey="p" href="rep_trans.html">Prev</a> </td> 159 <td width="20%" align="center"> 160 <a accesskey="u" href="rep.html">Up</a> 161 </td> 162 <td width="40%" align="right"> <a accesskey="n" href="rep_clock_skew.html">Next</a></td> 163 </tr> 164 <tr> 165 <td width="40%" align="left" valign="top">Transactional guarantees </td> 166 <td width="20%" align="center"> 167 <a accesskey="h" href="index.html">Home</a> 168 </td> 169 <td width="40%" align="right" valign="top"> Clock Skew</td> 170 </tr> 171 </table> 172 </div> 173 </body> 174</html> 175