1<!--$Id: app.so,v 1.32 2008/04/23 15:49:17 alanb 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: Building replicated applications</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/pri.html"><img src="../../images/prev.gif" alt="Prev"></a><a href="../toc.html"><img src="../../images/ref.gif" alt="Ref"></a><a href="../rep/mgr_meth.html"><img src="../../images/next.gif" alt="Next"></a> 14</td></tr></table> 15<p align=center><b>Building replicated applications</b></p> 16<p>The simplest way to build a replicated Berkeley DB application is to first 17build (and debug!) the transactional version of the same application. 18Then, add a thin replication layer: application initialization must be 19changed and the application's communication infrastructure must be 20added.</p> 21<p>The application initialization changes are relatively simple. 22Replication Manager provides a communication infrastructure, but 23in order to use the Base replication API you must provide your own.</p> 24<p>For implementation reasons, all replicated databases must reside in 25the data directories set from <a href="../../api_c/env_set_data_dir.html">DB_ENV->set_data_dir</a> (or in the 26default environment home directory, if not using 27<a href="../../api_c/env_set_data_dir.html">DB_ENV->set_data_dir</a>), rather than in a subdirectory below the 28specified directory. Care must be taken in applications using 29relative pathnames and changing working directories after opening the 30environment. In such applications the replication initialization code 31may not be able to locate the databases, and applications that change 32their working directories may need to use absolute pathnames.</p> 33<p>During application initialization, the application performs 34three additional tasks: first, it must specify the <a href="../../api_c/env_open.html#DB_INIT_REP">DB_INIT_REP</a> 35flag when opening its database environment and additionally, a 36Replication Manager application must also specify the <a href="../../api_c/env_open.html#DB_THREAD">DB_THREAD</a> flag; 37second, it must provide Berkeley DB information about its communications 38infrastructure; and third, it must start the Berkeley DB replication system. 39Generally, a replicated application will do normal Berkeley DB recovery and 40configuration, exactly like any other transactional application.</p> 41<p>Replication Manager applications configure the built-in communications 42infrastructure by calling the <a href="../../api_c/repmgr_local_site.html">DB_ENV->repmgr_set_local_site</a> method 43once and the <a href="../../api_c/repmgr_remote_site.html">DB_ENV->repmgr_add_remote_site</a> method zero or more 44times. Once the environment has been opened, the application starts 45the replication system by calling the <a href="../../api_c/repmgr_start.html">DB_ENV->repmgr_start</a> method.</p> 46<p>If using the Base replication API, the application calls the 47<a href="../../api_c/rep_transport.html">DB_ENV->rep_set_transport</a> method to configure the entry point to its own 48communications infrastructure, and then it calls the 49<a href="../../api_c/rep_start.html">DB_ENV->rep_start</a> method to join or create the replication group.</p> 50<p>When starting the replication system, an application has two choices: 51it may choose the group master site explicitly, or alternatively it 52may configure all group members as clients and then call for an 53election, letting the clients select the master from among 54themselves. Either is correct, and the choice is entirely up to the 55application.</p> 56<p>For an application that uses the Base replication API, the result of 57calling <a href="../../api_c/rep_start.html">DB_ENV->rep_start</a> is usually the discovery of a master, or the 58declaration of the local environment as the master. If a master has 59not been discovered after a reasonable amount of time, the application 60should call <a href="../../api_c/rep_elect.html">DB_ENV->rep_elect</a> to call for an election.</p> 61<p>Replication Manager applications have these same two choices. But 62they configure their start-up behavior simply by setting the flags 63parameter to the <a href="../../api_c/repmgr_start.html">DB_ENV->repmgr_start</a> method.</p> 64<p>Consider the case of multiple processes or multiple environment handles 65that modify databases in the replicated environment. All modifications 66must be done on the master environment. The first process to join or 67create the master environment must call both the 68<a href="../../api_c/rep_transport.html">DB_ENV->rep_set_transport</a> method and the <a href="../../api_c/rep_start.html">DB_ENV->rep_start</a> method. Subsequent 69replication processes must at least call the <a href="../../api_c/rep_transport.html">DB_ENV->rep_set_transport</a> method. 70Those processes may call the <a href="../../api_c/rep_start.html">DB_ENV->rep_start</a> method (as long as they use the 71same master or client argument). If multiple processes are modifying 72the master environment there must be a unified communication 73infrastructure such that messages arriving at clients have a single 74master ID. Additionally the application must be structured so that all 75incoming messages are able to be processed by a single <a href="../../api_c/env_class.html">DB_ENV</a> 76handle.</p> 77<p>Note that not all processes running in replicated environments need to 78call <a href="../../api_c/rep_transport.html">DB_ENV->rep_set_transport</a> or <a href="../../api_c/rep_start.html">DB_ENV->rep_start</a>. Read-only 79processes running in a master environment do not need to be configured 80for replication in any way. Processes running in a client environment 81are read-only by definition, and so do not need to be configured for 82replication either (although, in the case of clients that may become 83masters, it is usually simplest to configure for replication on process 84startup rather than trying to reconfigure when the client becomes a 85master). Obviously, at least one thread of control on each client must 86be configured for replication as messages must be passed between the 87master and the client.</p> 88<p>Any site in a replication group may have its own private 89transactional databases in the environment as well. A site may 90create a local database by using the <a href="../../api_c/db_set_flags.html#DB_TXN_NOT_DURABLE">DB_TXN_NOT_DURABLE</a> 91flag to the <a href="../../api_c/db_set_flags.html">DB->set_flags</a>. The application 92must never create a private database with the same name 93as a database replicated across the entire environment 94as data corruption can result.</p> 95<p>For implementation reasons, all incoming replication messages must be 96processed using the same <a href="../../api_c/env_class.html">DB_ENV</a> handle. It is not required that 97a single thread of control process all messages, only that all threads 98of control processing messages use the same handle.</p> 99<p>No additional calls are required to shut down a database environment 100participating in a replication group. The application should shut down 101the environment in the usual manner, by calling the <a href="../../api_c/env_close.html">DB_ENV->close</a> method. 102For Replication Manager applications, this also terminates all network 103connections and background processing threads.</p> 104<table width="100%"><tr><td><br></td><td align=right><a href="../rep/pri.html"><img src="../../images/prev.gif" alt="Prev"></a><a href="../toc.html"><img src="../../images/ref.gif" alt="Ref"></a><a href="../rep/mgr_meth.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