1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
|
<!--$Id: app.html,v 1.1.1.1 2003/11/20 22:14:20 toshok Exp $-->
<!--Copyright 1997-2002 by Sleepycat Software, Inc.-->
<!--All rights reserved.-->
<!--See the file LICENSE for redistribution information.-->
<html>
<head>
<title>Berkeley DB Reference Guide: Building replicated applications</title>
<meta name="description" content="Berkeley DB: An embedded database programmatic toolkit.">
<meta name="keywords" content="embedded,database,programmatic,toolkit,b+tree,btree,hash,hashing,transaction,transactions,locking,logging,access method,access methods,java,C,C++">
</head>
<body bgcolor=white>
<table width="100%"><tr valign=top>
<td><h3><dl><dt>Berkeley DB Reference Guide:<dd>Berkeley DB Replication</dl></h3></td>
<td align=right><a href="../../ref/rep/pri.html"><img src="../../images/prev.gif" alt="Prev"></a><a href="../../reftoc.html"><img src="../../images/ref.gif" alt="Ref"></a><a href="../../ref/rep/comm.html"><img src="../../images/next.gif" alt="Next"></a>
</td></tr></table>
<p>
<h1 align=center>Building replicated applications</h1>
<p>The simplest way to build a replicated Berkeley DB application is to first
build (and debug!) the transactional version of the same application.
Then, add a thin replication layer to the application. All highly available
applications use the following additional four Berkeley DB methods:
<a href="../../api_c/rep_elect.html">DB_ENV->rep_elect</a>, <a href="../../api_c/rep_message.html">DB_ENV->rep_process_message</a>, <a href="../../api_c/rep_start.html">DB_ENV->rep_start</a> and
<a href="../../api_c/rep_transport.html">DB_ENV->set_rep_transport</a> and may also use the configuration method
<a href="../../api_c/rep_limit.html">DB_ENV->set_rep_limit</a>:
<p><dl compact>
<p><dt><a href="../../api_c/rep_transport.html">DB_ENV->set_rep_transport</a><dd>The <a href="../../api_c/rep_transport.html">DB_ENV->set_rep_transport</a> method configures the replication system's
communications infrastructure.
<p><dt><a href="../../api_c/rep_start.html">DB_ENV->rep_start</a><dd>The <a href="../../api_c/rep_start.html">DB_ENV->rep_start</a> method configures (or reconfigures) an existing database
environment to be a replication master or client.
<p><dt><a href="../../api_c/rep_message.html">DB_ENV->rep_process_message</a><dd>The <a href="../../api_c/rep_message.html">DB_ENV->rep_process_message</a> method is used to process incoming messages from other
environments in the replication group. For clients, it is responsible
for accepting log records and updating the local databases based on
messages from the master. For both the master and the clients, it is
responsible for handling administrative functions (for example, the
protocol for dealing with lost messages), and permitting new clients to
join an active replication group.
<p><dt><a href="../../api_c/rep_elect.html">DB_ENV->rep_elect</a><dd>The <a href="../../api_c/rep_elect.html">DB_ENV->rep_elect</a> method causes the replication group to elect a new
master; it is called whenever contact with the master is lost.
<p><dt><a href="../../api_c/rep_limit.html">DB_ENV->set_rep_limit</a><dd>The <a href="../../api_c/rep_limit.html">DB_ENV->set_rep_limit</a> imposes an upper bound on the amount of data
that will be sent in response to a single call to <a href="../../api_c/rep_message.html">DB_ENV->rep_process_message</a>.
</dl>
<p>To add replication to a Berkeley DB application, application initialization
must be changed and the application's communications infrastructure must
be written. The application initialization changes are relatively
simple, but the communications infrastructure code can be complex.
<p>During application initialization, the application performs two
additional tasks: first, it must provide Berkeley DB information about its
communications infrastructure, and second, it must start the Berkeley DB
replication system. Generally, a replicated application will do normal
Berkeley DB recovery and configuration, exactly like any other transactional
application. Then, once the database environment has been opened, it
will call the <a href="../../api_c/rep_transport.html">DB_ENV->set_rep_transport</a> method to configure Berkeley DB for replication,
and then will call the <a href="../../api_c/rep_start.html">DB_ENV->rep_start</a> method to join or create the
replication group.
<p>When calling <a href="../../api_c/rep_start.html">DB_ENV->rep_start</a>, the application has two choices:
specifically configure the master for the replication group, or,
alternatively, configure all group members as clients and then call an
election, letting the clients select the master from among themselves.
Either is correct, and the choice is entirely up to the application.
The result of calling <a href="../../api_c/rep_start.html">DB_ENV->rep_start</a> is usually the discovery of a
master, or the declaration of the local environment as the master. If
a master has not been discovered after a reasonable amount of time, the
application should call <a href="../../api_c/rep_elect.html">DB_ENV->rep_elect</a> to call for an election.
<p>In the case of multiple processes accessing a replicated environment,
all of the threads of control expecting to modify databases in the
environment or process replication messages must call the
<a href="../../api_c/rep_start.html">DB_ENV->rep_start</a> method. Note that not all processes running in replicated
environments need to call <a href="../../api_c/rep_transport.html">DB_ENV->set_rep_transport</a> or <a href="../../api_c/rep_start.html">DB_ENV->rep_start</a>.
Read-only processes running in a master environment do not need to be
configured for replication in any way. Processes running in a client
environment are read-only by definition, and so do not need to be
configured for replication either (although, in the case of clients that
may become masters, it is usually simplest to configure for replication
on process startup rather than trying to reconfigure when the client
becomes a master). Obviously, at least one thread of control on each
client must be configured for replication as messages must be passed
between the master and the client.
<p>Databases are generally opened read-write on both clients and masters
in order to simplify upgrading replication clients to be masters. (If
databases are opened read-only on clients, and the client is then
upgraded to be the master, the client would have to close and reopen
all of its databases in order to support database update queries.)
However, even though the database is opened read-write on the client,
any attempt to update it will result in an error until the client is
reconfigured as a master. No databases can be opened on clients before
calling <a href="../../api_c/rep_start.html">DB_ENV->rep_start</a>, and attempting to do so will result in an
error.
<p>There are no additional interface calls required to shut down a database
environment participating in a replication group. The application
should shut down the environment in the usual manner, by calling the
<a href="../../api_c/env_close.html">DB_ENV->close</a> method.
<table width="100%"><tr><td><br></td><td align=right><a href="../../ref/rep/pri.html"><img src="../../images/prev.gif" alt="Prev"></a><a href="../../reftoc.html"><img src="../../images/ref.gif" alt="Ref"></a><a href="../../ref/rep/comm.html"><img src="../../images/next.gif" alt="Next"></a>
</td></tr></table>
<p><font size=1><a href="http://www.sleepycat.com">Copyright Sleepycat Software</a></font>
</body>
</html>
|
