mirror of
https://github.com/berkeleydb/libdb.git
synced 2024-11-17 01:26:25 +00:00
341 lines
12 KiB
HTML
341 lines
12 KiB
HTML
|
<?xml version="1.0" encoding="UTF-8" standalone="no"?>
|
|||
|
|
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
|
|||
|
|
<html xmlns="http://www.w3.org/1999/xhtml">
|
|||
|
|
<head>
|
|||
|
|
<meta http-equiv="Content-Type" content="text/html; charset=UTF-8" />
|
|||
|
|
<title>Chapter 3. The DB Replication Manager</title>
|
|||
|
|
<link rel="stylesheet" href="gettingStarted.css" type="text/css" />
|
|||
|
|
<meta name="generator" content="DocBook XSL Stylesheets V1.73.2" />
|
|||
|
|
<link rel="start" href="index.html" title="Getting Started with Replicated Berkeley DB Applications" />
|
|||
|
|
<link rel="up" href="index.html" title="Getting Started with Replicated Berkeley DB Applications" />
|
|||
|
|
<link rel="prev" href="simpleprogramlisting.html" title="Program Listing" />
|
|||
|
|
<link rel="next" href="rep_init_code.html" title="Starting and Stopping Replication" />
|
|||
|
|
</head>
|
|||
|
|
<body>
|
|||
|
|
<div xmlns="" class="navheader">
|
|||
|
|
<div class="libver">
|
|||
|
|
<p>Library Version 11.2.5.2</p>
|
|||
|
|
</div>
|
|||
|
|
<table width="100%" summary="Navigation header">
|
|||
|
|
<tr>
|
|||
|
|
<th colspan="3" align="center">Chapter 3. The DB Replication Manager</th>
|
|||
|
|
</tr>
|
|||
|
|
<tr>
|
|||
|
|
<td width="20%" align="left"><a accesskey="p" href="simpleprogramlisting.html">Prev</a> </td>
|
|||
|
|
<th width="60%" align="center"> </th>
|
|||
|
|
<td width="20%" align="right"> <a accesskey="n" href="rep_init_code.html">Next</a></td>
|
|||
|
|
</tr>
|
|||
|
|
</table>
|
|||
|
|
<hr />
|
|||
|
|
</div>
|
|||
|
|
<div class="chapter" lang="en" xml:lang="en">
|
|||
|
|
<div class="titlepage">
|
|||
|
|
<div>
|
|||
|
|
<div>
|
|||
|
|
<h2 class="title"><a id="repapp"></a>Chapter 3. The DB Replication Manager</h2>
|
|||
|
|
</div>
|
|||
|
|
</div>
|
|||
|
|
</div>
|
|||
|
|
<div class="toc">
|
|||
|
|
<p>
|
|||
|
|
<b>Table of Contents</b>
|
|||
|
|
</p>
|
|||
|
|
<dl>
|
|||
|
|
<dt>
|
|||
|
|
<span class="sect1">
|
|||
|
|
<a href="repapp.html#repmgr_grpmgmt">The DB_SITE Handle</a>
|
|||
|
|
</span>
|
|||
|
|
</dt>
|
|||
|
|
<dt>
|
|||
|
|
<span class="sect1">
|
|||
|
|
<a href="rep_init_code.html">
|
|||
|
|
Starting and Stopping Replication
|
|||
|
|
</a>
|
|||
|
|
</span>
|
|||
|
|
</dt>
|
|||
|
|
<dd>
|
|||
|
|
<dl>
|
|||
|
|
<dt>
|
|||
|
|
<span class="sect2">
|
|||
|
|
<a href="rep_init_code.html#election_flags">Managing Election Policies</a>
|
|||
|
|
</span>
|
|||
|
|
</dt>
|
|||
|
|
<dt>
|
|||
|
|
<span class="sect2">
|
|||
|
|
<a href="rep_init_code.html#thread_count">Selecting the Number of Threads</a>
|
|||
|
|
</span>
|
|||
|
|
</dt>
|
|||
|
|
</dl>
|
|||
|
|
</dd>
|
|||
|
|
<dt>
|
|||
|
|
<span class="sect1">
|
|||
|
|
<a href="repmgr_init_example_c.html">Adding the Replication Manager to
|
|||
|
|
<span>ex_rep_gsg_simple</span>
|
|||
|
|
|
|||
|
|
|
|||
|
|
</a>
|
|||
|
|
</span>
|
|||
|
|
</dt>
|
|||
|
|
<dt>
|
|||
|
|
<span class="sect1">
|
|||
|
|
<a href="fwrkpermmessage.html">Permanent Message Handling</a>
|
|||
|
|
</span>
|
|||
|
|
</dt>
|
|||
|
|
<dd>
|
|||
|
|
<dl>
|
|||
|
|
<dt>
|
|||
|
|
<span class="sect2">
|
|||
|
|
<a href="fwrkpermmessage.html#fmwrkpermpolicy">Identifying Permanent Message Policies</a>
|
|||
|
|
</span>
|
|||
|
|
</dt>
|
|||
|
|
<dt>
|
|||
|
|
<span class="sect2">
|
|||
|
|
<a href="fwrkpermmessage.html#fmwrkpermtimeout">Setting the Permanent Message Timeout</a>
|
|||
|
|
</span>
|
|||
|
|
</dt>
|
|||
|
|
<dt>
|
|||
|
|
<span class="sect2">
|
|||
|
|
<a href="fwrkpermmessage.html#perm2fmwrkexample">Adding a Permanent Message Policy to
|
|||
|
|
<span>ex_rep_gsg_repmgr</span>
|
|||
|
|
|
|||
|
|
|
|||
|
|
</a>
|
|||
|
|
</span>
|
|||
|
|
</dt>
|
|||
|
|
</dl>
|
|||
|
|
</dd>
|
|||
|
|
<dt>
|
|||
|
|
<span class="sect1">
|
|||
|
|
<a href="electiontimes.html">Managing Election Times</a>
|
|||
|
|
</span>
|
|||
|
|
</dt>
|
|||
|
|
<dd>
|
|||
|
|
<dl>
|
|||
|
|
<dt>
|
|||
|
|
<span class="sect2">
|
|||
|
|
<a href="electiontimes.html#electiontimeout">Managing Election Timeouts</a>
|
|||
|
|
</span>
|
|||
|
|
</dt>
|
|||
|
|
<dt>
|
|||
|
|
<span class="sect2">
|
|||
|
|
<a href="electiontimes.html#electretrytime">Managing Election Retry Times</a>
|
|||
|
|
</span>
|
|||
|
|
</dt>
|
|||
|
|
</dl>
|
|||
|
|
</dd>
|
|||
|
|
<dt>
|
|||
|
|
<span class="sect1">
|
|||
|
|
<a href="fmwrkconnectretry.html">Managing Connection Retries</a>
|
|||
|
|
</span>
|
|||
|
|
</dt>
|
|||
|
|
<dt>
|
|||
|
|
<span class="sect1">
|
|||
|
|
<a href="heartbeats.html">Managing Heartbeats</a>
|
|||
|
|
</span>
|
|||
|
|
</dt>
|
|||
|
|
</dl>
|
|||
|
|
</div>
|
|||
|
|
<p>
|
|||
|
|
The easiest way to add replication to your transactional
|
|||
|
|
application is to use the Replication Manager. The Replication Manager provides a comprehensive
|
|||
|
|
communications layer that enables replication. For a brief listing
|
|||
|
|
of the Replication Manager's feature set, see
|
|||
|
|
<a class="xref" href="apioverview.html#repframeworkoverview" title="Replication Manager Overview">Replication Manager Overview</a>.
|
|||
|
|
</p>
|
|||
|
|
<p>
|
|||
|
|
To use the Replication Manager, you make use of a combination of the
|
|||
|
|
<code class="classname">DB_SITE</code>
|
|||
|
|
|
|||
|
|
class and related methods, plus special methods off the
|
|||
|
|
<span><code class="classname">DB_ENV</code> class.</span>
|
|||
|
|
|
|||
|
|
That is:
|
|||
|
|
</p>
|
|||
|
|
<div class="orderedlist">
|
|||
|
|
<ol type="1">
|
|||
|
|
<li>
|
|||
|
|
<p>
|
|||
|
|
Create an environment handle as normal.
|
|||
|
|
</p>
|
|||
|
|
</li>
|
|||
|
|
<li>
|
|||
|
|
<p>
|
|||
|
|
Configure your environment handle as needed (e.g. set the
|
|||
|
|
error file and error prefix values, if desired).
|
|||
|
|
</p>
|
|||
|
|
</li>
|
|||
|
|
<li>
|
|||
|
|
<p>
|
|||
|
|
Use the Replication Manager replication classes and methods to configure
|
|||
|
|
the Replication Manager. Using these classes and methods causes DB
|
|||
|
|
to know that you are using the Replication Manager.
|
|||
|
|
</p>
|
|||
|
|
<p>
|
|||
|
|
Configuring the Replication Manager entails setting the replication
|
|||
|
|
environment's priority, setting the TCP/IP address that
|
|||
|
|
this replication environment will use for incoming
|
|||
|
|
replication messages, identifying TCP/IP addresses of other
|
|||
|
|
replication environments, setting the number of replication
|
|||
|
|
environments in the replication group, and so forth. These
|
|||
|
|
actions are discussed throughout the remainder of this
|
|||
|
|
chapter.
|
|||
|
|
</p>
|
|||
|
|
</li>
|
|||
|
|
<li>
|
|||
|
|
<p>
|
|||
|
|
Open your environment handle. When you do this, be sure to
|
|||
|
|
specify
|
|||
|
|
|
|||
|
|
<span>
|
|||
|
|
<code class="literal">DB_INIT_REP</code> and
|
|||
|
|
<code class="literal">DB_THREAD</code> to your open flags. (This
|
|||
|
|
is in addition to the flags that you normally use for a
|
|||
|
|
single-threaded transactional application). The first
|
|||
|
|
of these causes replication to be initialized for the
|
|||
|
|
application. The second causes your environment handle
|
|||
|
|
to be free-threaded (thread safe). Both flags are
|
|||
|
|
required for Replication Manager usage.
|
|||
|
|
</span>
|
|||
|
|
|
|||
|
|
|
|||
|
|
</p>
|
|||
|
|
</li>
|
|||
|
|
<li>
|
|||
|
|
<p>
|
|||
|
|
Start replication by calling
|
|||
|
|
<span><code class="methodname">DB_ENV->repmgr_start()</code>.</span>
|
|||
|
|
|
|||
|
|
|
|||
|
|
</p>
|
|||
|
|
</li>
|
|||
|
|
<li>
|
|||
|
|
<p>
|
|||
|
|
Open your databases as needed. Masters must open their databases
|
|||
|
|
for read and write activity. Replicas can open their databases
|
|||
|
|
for read-only activity, but doing so means they must
|
|||
|
|
re-open the databases if the replica ever becomes a master.
|
|||
|
|
Either way, replicas should never attempt to write to the
|
|||
|
|
database(s) directly.
|
|||
|
|
</p>
|
|||
|
|
</li>
|
|||
|
|
</ol>
|
|||
|
|
</div>
|
|||
|
|
<div class="note" style="margin-left: 0.5in; margin-right: 0.5in;">
|
|||
|
|
<h3 class="title">Note</h3>
|
|||
|
|
<p>
|
|||
|
|
The Replication Manager allows you to only use one environment handle per
|
|||
|
|
process.
|
|||
|
|
</p>
|
|||
|
|
</div>
|
|||
|
|
<p>
|
|||
|
|
When you are ready to shut down your application:
|
|||
|
|
</p>
|
|||
|
|
<div class="orderedlist">
|
|||
|
|
<ol type="1">
|
|||
|
|
<li>
|
|||
|
|
<p>
|
|||
|
|
Close any open
|
|||
|
|
<code class="classname">DB_SITE</code>
|
|||
|
|
|
|||
|
|
handles that you might have open.
|
|||
|
|
</p>
|
|||
|
|
</li>
|
|||
|
|
<li>
|
|||
|
|
<p>
|
|||
|
|
Close your databases
|
|||
|
|
</p>
|
|||
|
|
</li>
|
|||
|
|
<li>
|
|||
|
|
<p>
|
|||
|
|
Close your environment. This causes replication to stop as
|
|||
|
|
well.
|
|||
|
|
</p>
|
|||
|
|
</li>
|
|||
|
|
</ol>
|
|||
|
|
</div>
|
|||
|
|
<div class="note" style="margin-left: 0.5in; margin-right: 0.5in;">
|
|||
|
|
<h3 class="title">Note</h3>
|
|||
|
|
<p>
|
|||
|
|
Before you can use the Replication Manager, you may have to enable it
|
|||
|
|
in your DB library. This is
|
|||
|
|
<span class="emphasis"><em>not</em></span> a requirement for Microsoft
|
|||
|
|
Windows systems, or Unix systems that use pthread
|
|||
|
|
mutexes by default. Other systems, notably BSD and
|
|||
|
|
BSD-derived systems (such as Mac OS X), must enable the
|
|||
|
|
Replication Manager when you configure the DB build.
|
|||
|
|
</p>
|
|||
|
|
<p>
|
|||
|
|
You do this by <span class="emphasis"><em>not</em></span> disabling
|
|||
|
|
replication and by configuring the library with POSIX
|
|||
|
|
threads support. In other words, replication must be
|
|||
|
|
turned on in the build (it is by default), and POSIX
|
|||
|
|
thread support must be enabled if it is not already by
|
|||
|
|
default. To do this, use the
|
|||
|
|
<code class="literal">--enable-pthread_api</code> switch on the
|
|||
|
|
configure script.
|
|||
|
|
</p>
|
|||
|
|
<p>
|
|||
|
|
For example:
|
|||
|
|
</p>
|
|||
|
|
<pre class="programlisting">../dist/configure --enable-pthread-api</pre>
|
|||
|
|
</div>
|
|||
|
|
<div class="sect1" lang="en" xml:lang="en">
|
|||
|
|
<div class="titlepage">
|
|||
|
|
<div>
|
|||
|
|
<div>
|
|||
|
|
<h2 class="title" style="clear: both"><a id="repmgr_grpmgmt"></a>The DB_SITE Handle</h2>
|
|||
|
|
</div>
|
|||
|
|
</div>
|
|||
|
|
</div>
|
|||
|
|
<p>
|
|||
|
|
Before continuing, it is useful to mention the
|
|||
|
|
<code class="classname">DB_SITE</code>
|
|||
|
|
|
|||
|
|
handle. This class is used to configure important attributes about
|
|||
|
|
a site such as its host name and port number, and whether it is the
|
|||
|
|
local site. It is also used to indicate whether a site is a
|
|||
|
|
<span class="emphasis"><em>group creator</em></span>, which is important when you are
|
|||
|
|
starting the very first site in a replication group for the very
|
|||
|
|
first time.
|
|||
|
|
</p>
|
|||
|
|
<p>
|
|||
|
|
The
|
|||
|
|
<code class="classname">DB_SITE</code>
|
|||
|
|
|
|||
|
|
handle is used whenever you start up a site. It must be closed
|
|||
|
|
before you close your
|
|||
|
|
<code class="classname">DB_ENV</code>
|
|||
|
|
|
|||
|
|
handle.
|
|||
|
|
</p>
|
|||
|
|
<p>
|
|||
|
|
The
|
|||
|
|
<code class="classname">DB_SITE</code>
|
|||
|
|
|
|||
|
|
handle is plays an important role in replication group management. This topic
|
|||
|
|
is fully described in the <em class="citetitle">Berkeley DB Programmer's Reference Guide</em>.
|
|||
|
|
</p>
|
|||
|
|
</div>
|
|||
|
|
</div>
|
|||
|
|
<div class="navfooter">
|
|||
|
|
<hr />
|
|||
|
|
<table width="100%" summary="Navigation footer">
|
|||
|
|
<tr>
|
|||
|
|
<td width="40%" align="left"><a accesskey="p" href="simpleprogramlisting.html">Prev</a> </td>
|
|||
|
|
<td width="20%" align="center"> </td>
|
|||
|
|
<td width="40%" align="right"> <a accesskey="n" href="rep_init_code.html">Next</a></td>
|
|||
|
|
</tr>
|
|||
|
|
<tr>
|
|||
|
|
<td width="40%" align="left" valign="top">Program Listing </td>
|
|||
|
|
<td width="20%" align="center">
|
|||
|
|
<a accesskey="h" href="index.html">Home</a>
|
|||
|
|
</td>
|
|||
|
|
<td width="40%" align="right" valign="top">
|
|||
|
|
Starting and Stopping Replication
|
|||
|
|
</td>
|
|||
|
|
</tr>
|
|||
|
|
</table>
|
|||
|
|
</div>
|
|||
|
|
</body>
|
|||
|
|
</html>
|