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>Building replicated applications</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_pri.html" title="Replication environment priorities" /> 12 <link rel="next" href="rep_mgr_meth.html" title="Replication Manager methods" /> 13 </head> 14 <body> 15 <div class="navheader"> 16 <table width="100%" summary="Navigation header"> 17 <tr> 18 <th colspan="3" align="center">Building replicated applications</th> 19 </tr> 20 <tr> 21 <td width="20%" align="left"><a accesskey="p" href="rep_pri.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_mgr_meth.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_app"></a>Building replicated applications</h2> 35 </div> 36 </div> 37 </div> 38 <p>The simplest way to build a replicated Berkeley DB application is to first 39build (and debug!) the transactional version of the same application. 40Then, add a thin replication layer: application initialization must be 41changed and the application's communication infrastructure must be 42added.</p> 43 <p>The application initialization changes are relatively simple. 44Replication Manager provides a communication infrastructure, but 45in order to use the replication Base APIs you must provide your own.</p> 46 <p>For implementation reasons, all replicated databases must reside in 47the data directories set from <a href="../api_reference/C/envset_data_dir.html" class="olink">DB_ENV->set_data_dir()</a> (or in the 48default environment home directory, if not using 49<a href="../api_reference/C/envset_data_dir.html" class="olink">DB_ENV->set_data_dir()</a>), rather than in a subdirectory below the 50specified directory. Care must be taken in applications using 51relative pathnames and changing working directories after opening the 52environment. In such applications the replication initialization code 53may not be able to locate the databases, and applications that change 54their working directories may need to use absolute pathnames.</p> 55 <p>During application initialization, the application performs 56three additional tasks: first, it must specify the <a href="../api_reference/C/envopen.html#open_DB_INIT_REP" class="olink">DB_INIT_REP</a> 57flag when opening its database environment and additionally, a 58Replication Manager application must also specify the <a href="../api_reference/C/dbopen.html#open_DB_THREAD" class="olink">DB_THREAD</a> flag; 59second, it must provide Berkeley DB information about its communications 60infrastructure; and third, it must start the Berkeley DB replication system. 61Generally, a replicated application will do normal Berkeley DB recovery and 62configuration, exactly like any other transactional application.</p> 63 <p>Replication Manager applications configure the built-in communications 64infrastructure by calling the <a href="../api_reference/C/repmgrlocal_site.html" class="olink">DB_ENV->repmgr_set_local_site()</a> method 65once and the <a href="../api_reference/C/repmgrremote_site.html" class="olink">DB_ENV->repmgr_add_remote_site()</a> method zero or more 66times. Once the environment has been opened, the application starts 67the replication system by calling the <a href="../api_reference/C/repmgrstart.html" class="olink">DB_ENV->repmgr_start()</a> method.</p> 68 <p>A Base API application calls the 69<a href="../api_reference/C/reptransport.html" class="olink">DB_ENV->rep_set_transport()</a> method to configure the entry point to its own 70communications infrastructure, and then calls the 71<a href="../api_reference/C/repstart.html" class="olink">DB_ENV->rep_start()</a> method to join or create the replication group.</p> 72 <p>When starting the replication system, an application has two choices: 73it may choose the group master site explicitly, or alternatively it 74may configure all group members as clients and then call for an 75election, letting the clients select the master from among 76themselves. Either is correct, and the choice is entirely up to the 77application.</p> 78 <p>Replication Manager applications make this choice simply by setting 79the flags parameter to the <a href="../api_reference/C/repmgrstart.html" class="olink">DB_ENV->repmgr_start()</a> method.</p> 80 <p>For a Base API application, the result of 81calling <a href="../api_reference/C/repstart.html" class="olink">DB_ENV->rep_start()</a> is usually the discovery of a master, or the 82declaration of the local environment as the master. If a master has 83not been discovered after a reasonable amount of time, the application 84should call <a href="../api_reference/C/repelect.html" class="olink">DB_ENV->rep_elect()</a> to call for an election.</p> 85 <p>Consider a Base API application with multiple processes or multiple 86environment handles 87that modify databases in the replicated environment. All modifications 88must be done on the master environment. The first process to join or 89create the master environment must call both the 90<a href="../api_reference/C/reptransport.html" class="olink">DB_ENV->rep_set_transport()</a> and the <a href="../api_reference/C/repstart.html" class="olink">DB_ENV->rep_start()</a> method. Subsequent 91replication processes must at least call the <a href="../api_reference/C/reptransport.html" class="olink">DB_ENV->rep_set_transport()</a> method. 92Those processes may call the <a href="../api_reference/C/repstart.html" class="olink">DB_ENV->rep_start()</a> method (as long as they use the 93same master or client argument). If multiple processes are modifying 94the master environment there must be a unified communication 95infrastructure such that messages arriving at clients have a single 96master ID. Additionally the application must be structured so that all 97incoming messages are able to be processed by a single <a href="../api_reference/C/env.html" class="olink">DB_ENV</a> 98handle.</p> 99 <p>Note that not all processes running in replicated environments need to 100call <a href="../api_reference/C/repmgrstart.html" class="olink">DB_ENV->repmgr_start()</a>, <a href="../api_reference/C/reptransport.html" class="olink">DB_ENV->rep_set_transport()</a> or <a href="../api_reference/C/repstart.html" class="olink">DB_ENV->rep_start()</a>. Read-only 101processes running in a master environment do not need to be configured 102for replication in any way. Processes running in a client environment 103are read-only by definition, and so do not need to be configured for 104replication either (although, in the case of clients that may become 105masters, it is usually simplest to configure for replication on process 106startup rather than trying to reconfigure when the client becomes a 107master). Obviously, at least one thread of control on each client must 108be configured for replication as messages must be passed between the 109master and the client.</p> 110 <p>Any site in a replication group may have its own private 111transactional databases in the environment as well. A site may 112create a local database by specifying the <a href="../api_reference/C/dbset_flags.html#dbset_flags_DB_TXN_NOT_DURABLE" class="olink">DB_TXN_NOT_DURABLE</a> 113flag to the <a href="../api_reference/C/dbset_flags.html" class="olink">DB->set_flags()</a> method. The application 114must never create a private database with the same name 115as a database replicated across the entire environment 116as data corruption can result.</p> 117 <p>For implementation reasons, Base API applications must process 118all incoming replication messages 119using the same <a href="../api_reference/C/env.html" class="olink">DB_ENV</a> handle. It is not required that 120a single thread of control process all messages, only that all threads 121of control processing messages use the same handle.</p> 122 <p>No additional calls are required to shut down a database environment 123participating in a replication group. The application should shut down 124the environment in the usual manner, by calling the <a href="../api_reference/C/envclose.html" class="olink">DB_ENV->close()</a> method. 125For Replication Manager applications, this also terminates all network 126connections and background processing threads.</p> 127 </div> 128 <div class="navfooter"> 129 <hr /> 130 <table width="100%" summary="Navigation footer"> 131 <tr> 132 <td width="40%" align="left"><a accesskey="p" href="rep_pri.html">Prev</a>��</td> 133 <td width="20%" align="center"> 134 <a accesskey="u" href="rep.html">Up</a> 135 </td> 136 <td width="40%" align="right">��<a accesskey="n" href="rep_mgr_meth.html">Next</a></td> 137 </tr> 138 <tr> 139 <td width="40%" align="left" valign="top">Replication environment priorities��</td> 140 <td width="20%" align="center"> 141 <a accesskey="h" href="index.html">Home</a> 142 </td> 143 <td width="40%" align="right" valign="top">��Replication Manager methods</td> 144 </tr> 145 </table> 146 </div> 147 </body> 148</html> 149