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>Chapter 1. Introduction</title> 7 <link rel="stylesheet" href="gettingStarted.css" type="text/css" /> 8 <meta name="generator" content="DocBook XSL Stylesheets V1.62.4" /> 9 <link rel="home" href="index.html" title="Getting Started with Replicated Berkeley DB Applications" /> 10 <link rel="up" href="index.html" title="Getting Started with Replicated Berkeley DB Applications" /> 11 <link rel="previous" href="preface.html" title="Preface" /> 12 <link rel="next" href="repadvantage.html" title="Replication Benefits" /> 13 </head> 14 <body> 15 <div class="navheader"> 16 <table width="100%" summary="Navigation header"> 17 <tr> 18 <th colspan="3" align="center">Chapter 1. Introduction</th> 19 </tr> 20 <tr> 21 <td width="20%" align="left"><a accesskey="p" href="preface.html">Prev</a> </td> 22 <th width="60%" align="center"> </th> 23 <td width="20%" align="right"> <a accesskey="n" href="repadvantage.html">Next</a></td> 24 </tr> 25 </table> 26 <hr /> 27 </div> 28 <div class="chapter" lang="en" xml:lang="en"> 29 <div class="titlepage"> 30 <div> 31 <div> 32 <h2 class="title"><a id="introduction"></a>Chapter 1. Introduction</h2> 33 </div> 34 </div> 35 <div></div> 36 </div> 37 <div class="toc"> 38 <p> 39 <b>Table of Contents</b> 40 </p> 41 <dl> 42 <dt> 43 <span class="sect1"> 44 <a href="introduction.html#overview">Overview</a> 45 </span> 46 </dt> 47 <dd> 48 <dl> 49 <dt> 50 <span class="sect2"> 51 <a href="introduction.html#repenvirons">Replication Environments</a> 52 </span> 53 </dt> 54 <dt> 55 <span class="sect2"> 56 <a href="introduction.html#repdbs">Replication Databases</a> 57 </span> 58 </dt> 59 <dt> 60 <span class="sect2"> 61 <a href="introduction.html#commlayer">Communications Layer</a> 62 </span> 63 </dt> 64 <dt> 65 <span class="sect2"> 66 <a href="introduction.html#masterselect">Selecting a Master</a> 67 </span> 68 </dt> 69 </dl> 70 </dd> 71 <dt> 72 <span class="sect1"> 73 <a href="repadvantage.html">Replication Benefits</a> 74 </span> 75 </dt> 76 <dt> 77 <span class="sect1"> 78 <a href="apioverview.html">The Replication APIs</a> 79 </span> 80 </dt> 81 <dd> 82 <dl> 83 <dt> 84 <span class="sect2"> 85 <a href="apioverview.html#repframeworkoverview">Replication Framework Overview</a> 86 </span> 87 </dt> 88 <dt> 89 <span class="sect2"> 90 <a href="apioverview.html#repapioverview">Replication API Overview</a> 91 </span> 92 </dt> 93 </dl> 94 </dd> 95 <dt> 96 <span class="sect1"> 97 <a href="elections.html">Holding Elections</a> 98 </span> 99 </dt> 100 <dd> 101 <dl> 102 <dt> 103 <span class="sect2"> 104 <a href="elections.html#influencingelections">Influencing Elections</a> 105 </span> 106 </dt> 107 <dt> 108 <span class="sect2"> 109 <a href="elections.html#winningelections">Winning Elections</a> 110 </span> 111 </dt> 112 <dt> 113 <span class="sect2"> 114 <a href="elections.html#switchingmasters">Switching Masters</a> 115 </span> 116 </dt> 117 </dl> 118 </dd> 119 <dt> 120 <span class="sect1"> 121 <a href="permmessages.html">Permanent Message Handling</a> 122 </span> 123 </dt> 124 <dd> 125 <dl> 126 <dt> 127 <span class="sect2"> 128 <a href="permmessages.html#permmessagenot">When Not to Manage 129 Permanent Messages</a> 130 </span> 131 </dt> 132 <dt> 133 <span class="sect2"> 134 <a href="permmessages.html#permmanage">Managing Permanent Messages</a> 135 </span> 136 </dt> 137 <dt> 138 <span class="sect2"> 139 <a href="permmessages.html#permimplement">Implementing Permanent 140 Message Handling</a> 141 </span> 142 </dt> 143 </dl> 144 </dd> 145 </dl> 146 </div> 147 <p> 148 This book provides a thorough introduction and discussion on 149 replication as used with Berkeley DB (DB). It begins by offering a 150 general overview to replication and the benefits it provides. It also 151 describes the APIs that you use to implement replication, and it 152 describes architecturally the things that you need to do to your 153 application code in order to use the replication APIs. Finally, it 154 discusses the differences in backup and restore strategies that you 155 might pursue when using replication, especially where it comes to log 156 file removal. 157 </p> 158 <p> 159 You should understand the concepts from the 160 <span> 161 <i class="citetitle">Berkeley DB Getting Started with Transaction Processing</i> 162 </span> 163 164 165 guide before reading this book. 166 </p> 167 <div class="sect1" lang="en" xml:lang="en"> 168 <div class="titlepage"> 169 <div> 170 <div> 171 <h2 class="title" style="clear: both"><a id="overview"></a>Overview</h2> 172 </div> 173 </div> 174 <div></div> 175 </div> 176 <p> 177 The DB replication APIs allow you to distribute your database 178 write operations (performed on a read-write master) to one or 179 more read-only <span class="emphasis"><em>replicas</em></span>. 180 For this reason, DB's replication implementation is said to be a 181 <span class="emphasis"><em>single master, multiple replica</em></span> replication strategy. 182 </p> 183 <p> 184 Note that your database write operations can occur only on the 185 master; any attempt to write to a replica results in an error 186 being 187 <span>returned to</span> 188 189 the DB API used to perform the write. 190 </p> 191 <p> 192 A single replication master and all of its replicas are referred 193 to as a <span class="emphasis"><em>replication group</em></span>. While all 194 members of the replication group can reside on the same 195 machine, usually each replication participant is placed on a 196 separate physical machine somewhere on the network. 197 </p> 198 <p> 199 Note that all replication applications must first be 200 transactional applications. The data that the master transmits 201 its replicas are log records that are generated as records are 202 updated. Upon transactional commit, the master transmits a 203 transaction record which tells the replicas to commit the 204 records they previously received from the master. In order for 205 all of this to work, your replicated application must also be a 206 transactional application. For this reason, it is 207 recommended that you write and debug your DB application as 208 a stand-alone transactional application before introducing the 209 replication layer to your code. 210 </p> 211 <p> 212 Finally, be aware that all machines participating in the 213 replication group must share identical 214 <span class="emphasis"><em>endianess</em></span>. Endianess is the byte-order 215 strategy used by the computing platform to store multibyte 216 numbers. Berkeley DB is sensitive to byte order and so your 217 replication infrastructure must be consistent in this area. 218 We expect to remove this requirement in some future 219 release of the product. 220 </p> 221 <div class="sect2" lang="en" xml:lang="en"> 222 <div class="titlepage"> 223 <div> 224 <div> 225 <h3 class="title"><a id="repenvirons"></a>Replication Environments</h3> 226 </div> 227 </div> 228 <div></div> 229 </div> 230 <p> 231 The most important requirement for a replication 232 participant is that it must use a unique Berkeley DB database 233 environment independent of all other replication 234 participants. So while multiple replication participants 235 can reside on the same physical machine, no two such participants 236 can share the same environment home directory. 237 </p> 238 <p> 239 For this reason, technically replication occurs between 240 unique <span class="emphasis"><em>database environments</em></span>. So in the strictest sense, 241 a replication group consists of a <span class="emphasis"><em>master 242 environment</em></span> and 243 one or more <span class="emphasis"><em>replica environments</em></span>. However, the reality 244 is that for production code, each such environment will 245 usually be located on its own unique machine. Consequently, 246 this manual sometimes talks about <span class="emphasis"><em>replication sites</em></span>, meaning the 247 unique combination of environment home directory, host and port that a specific 248 replication application is using. 249 </p> 250 <p> 251 There is no DB-specified limit to the number of 252 environments which can participate in a replication group. 253 The only limitation here is one of resources — 254 network bandwidth, for example. 255 </p> 256 <p> 257 (Note, however, that the replication framework does place a limit on the 258 number of environments you can use. See 259 <a href="apioverview.html#repframeworkoverview">Replication Framework Overview</a> 260 for details.) 261 </p> 262 <p> 263 Also, DB's replication implementation requires all 264 participating environments to be assigned IDs that are 265 locally unique to the given environment. Depending on the 266 replication APIs that you choose to use, you may or may not 267 need to manage this particular detail. 268 </p> 269 <p> 270 For detailed information on database environments, see 271 the <i class="citetitle">Berkeley DB Getting Started with Transaction Processing</i> 272 guide. For more information on environment IDs, see 273 the <i class="citetitle">Berkeley DB Programmer's Reference Guide</i>. 274 </p> 275 </div> 276 <div class="sect2" lang="en" xml:lang="en"> 277 <div class="titlepage"> 278 <div> 279 <div> 280 <h3 class="title"><a id="repdbs"></a>Replication Databases</h3> 281 </div> 282 </div> 283 <div></div> 284 </div> 285 <p> 286 DB's databases are managed and used in exactly the same way 287 as if you were writing a non-replicated application, with 288 a couple of caveats. First, the databases maintained in a replicated environment 289 must reside either in the <tt class="literal">ENV_HOME</tt> 290 directory, or in the directory identified by the 291 <tt class="methodname">DB_ENV->set_data_dir()</tt> 292 293 294 method. Unlike non-replication applications, you cannot place your 295 databases in a subdirectory below these locations. You should 296 also not use full path names for your databases or 297 environments as these are likely to break as to replicated 298 to other machines. 299 </p> 300 </div> 301 <div class="sect2" lang="en" xml:lang="en"> 302 <div class="titlepage"> 303 <div> 304 <div> 305 <h3 class="title"><a id="commlayer"></a>Communications Layer</h3> 306 </div> 307 </div> 308 <div></div> 309 </div> 310 <p> 311 In order to transmit database writes to the replication 312 replicas, DB requires a communications layer. 313 DB is agnostic as to what this layer should 314 look like. The only requirement is that it 315 be capable of passing two opaque data objects and an 316 environment ID from the master to its replicas without 317 corruption. 318 </p> 319 <p> 320 Because replicas are usually placed on different machines on 321 the network, the communications layer is usually some kind 322 of a network-aware implementation. Beyond that, its 323 implementation details are largely up to you. It could use 324 TCP/IP sockets, for example, or it could use 325 raw sockets if they perform better for your particular 326 application. 327 </p> 328 <p> 329 Note that you may not have to write your own communications 330 layer. DB provides a replication framework that 331 includes a fully-functional TCP/IP-based communications layer. 332 See <a href="apioverview.html">The Replication APIs</a> 333 for more information. 334 </p> 335 <p> 336 See the <i class="citetitle">Berkeley DB Programmer's Reference Guide</i> 337 for a description of how to 338 write your own custom replication communications layer. 339 </p> 340 </div> 341 <div class="sect2" lang="en" xml:lang="en"> 342 <div class="titlepage"> 343 <div> 344 <div> 345 <h3 class="title"><a id="masterselect"></a>Selecting a Master</h3> 346 </div> 347 </div> 348 <div></div> 349 </div> 350 <p> 351 Every replication group is allowed one and only one 352 master environment. Almost always, masters are selected by 353 holding an <span class="emphasis"><em>election</em></span>. All such 354 elections are performed by the underlying Berkeley DB 355 replication code so you have to do very little to 356 implement them. 357 </p> 358 <p> 359 When holding an election, replicas "vote" on who should 360 be the master. Among replicas participating in the 361 election, the one with the most up-to-date set of log 362 records will win the election. Note that it's possible 363 for there to be a tie. When this occurs, priorities are 364 used to select the master. See 365 <a href="elections.html">Holding Elections</a> 366 for details. 367 </p> 368 <p> 369 For more information on holding and managing elections, 370 see <a href="elections.html">Holding Elections</a>. 371 </p> 372 </div> 373 </div> 374 </div> 375 <div class="navfooter"> 376 <hr /> 377 <table width="100%" summary="Navigation footer"> 378 <tr> 379 <td width="40%" align="left"><a accesskey="p" href="preface.html">Prev</a> </td> 380 <td width="20%" align="center"> 381 <a accesskey="u" href="index.html">Up</a> 382 </td> 383 <td width="40%" align="right"> <a accesskey="n" href="repadvantage.html">Next</a></td> 384 </tr> 385 <tr> 386 <td width="40%" align="left" valign="top">Preface </td> 387 <td width="20%" align="center"> 388 <a accesskey="h" href="index.html">Home</a> 389 </td> 390 <td width="40%" align="right" valign="top"> Replication Benefits</td> 391 </tr> 392 </table> 393 </div> 394 </body> 395</html> 396