<?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>Running Replication using the db_replicate Utility</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="Berkeley DB Programmer's Reference Guide" />
<link rel="up" href="rep.html" title="Chapter 12. Berkeley DB Replication" />
<link rel="prev" href="rep_mgrmulti.html" title="Running Replication Manager in multiple processes" />
<link rel="next" href="rep_mgr_ack.html" title="Choosing a Replication Manager Ack Policy" />
</head>
<body>
<div class="navheader">
<table width="100%" summary="Navigation header">
<tr>
<th colspan="3" align="center">Running Replication using the db_replicate Utility</th>
</tr>
<tr>
<td width="20%" align="left"><a accesskey="p" href="rep_mgrmulti.html">Prev</a> </td>
<th width="60%" align="center">Chapter 12.
Berkeley DB Replication
</th>
<td width="20%" align="right"> <a accesskey="n" href="rep_mgr_ack.html">Next</a></td>
</tr>
</table>
<hr />
</div>
<div class="sect1" lang="en" xml:lang="en">
<div class="titlepage">
<div>
<div>
<h2 class="title" style="clear: both"><a id="rep_replicate"></a>Running Replication using the db_replicate Utility</h2>
</div>
</div>
</div>
<div class="toc">
<dl>
<dt>
<span class="sect2">
<a href="rep_replicate.html#id3867984">One Replication Process and Multiple Subordinate Processes</a>
</span>
</dt>
<dt>
<span class="sect2">
<a href="rep_replicate.html#id3868618">Common Use Case</a>
</span>
</dt>
<dt>
<span class="sect2">
<a href="rep_replicate.html#id3868784">Avoiding Rollback</a>
</span>
</dt>
<dt>
<span class="sect2">
<a href="rep_replicate.html#id3868880">When to Consider an Integrated HA Application</a>
</span>
</dt>
</dl>
</div>
<p>Replication Manager supports shared access to a database
environment from multiple processes. Berkeley DB provides a
replication-aware utility, db_replicate, that enables you to upgrade an existing Transactional Data Store
application, as discussed in the <a class="xref" href="transapp.html#transapp_intro" title="Transactional Data Store introduction">Transactional Data Store introduction</a> section,
to an HA application with
minor modifications. While the <a href="../api_reference/C/db_replicate.html" class="olink">db_replicate utility</a> simplifies the use
of replication with a TDS application, you
must still understand replication and its impact on the application.
</p>
<div class="sect2" lang="en" xml:lang="en">
<div class="titlepage">
<div>
<div>
<h3 class="title"><a id="id3867984"></a>One Replication Process and Multiple Subordinate Processes</h3>
</div>
</div>
</div>
<p>Based on the terminology introduced in the <a class="xref" href="rep_mgrmulti.html" title="Running Replication Manager in multiple processes">Running Replication Manager in multiple processes</a> section,
application processes are "subordinate processes" and the <a href="../api_reference/C/db_replicate.html" class="olink">db_replicate utility</a>
is the "primary replication process".</p>
<p>
You must consider the following items when
planning to use the <a href="../api_reference/C/db_replicate.html" class="olink">db_replicate utility</a> in combination with
a TDS application.
</p>
<div class="itemizedlist">
<ul type="disc">
<li>Memory regions
<p>
The <a href="../api_reference/C/db_replicate.html" class="olink">db_replicate utility</a> requires shared memory access among
separate processes, and therefore cannot be used with <a href="../api_reference/C/envopen.html#envopen_DB_PRIVATE" class="olink">DB_PRIVATE</a>.
</p></li>
<li>Multi-process implications
<p>
You must understand and accept all of the TDS implications
of multi-process use as specified in <a class="xref" href="transapp_app.html" title="Architecting Transactional Data Store applications">Architecting Transactional Data Store applications</a>. Special attention should be
paid to the coordination needed for unrelated processes to
start up correctly.
</p></li>
<li>Replication configuration
<p>
Several configuration settings are required for replication.
You must set the <a href="../api_reference/C/envopen.html#envopen_DB_INIT_REP" class="olink">DB_INIT_REP</a>
and <a href="../api_reference/C/dbopen.html#open_DB_THREAD" class="olink">DB_THREAD</a> flags for the <a href="../api_reference/C/envopen.html" class="olink">DB_ENV->open()</a> method.
Another required configuration item is the local address,
set via the <a href="../api_reference/C/repmgrlocal_site.html" class="olink">repmgr_set_local_site() method</a>.
Sites also need to know how to contact other sites via calls to the
<a href="../api_reference/C/repmgrremote_site.html" class="olink">repmgr_add_remote_site() method</a>.
Most replication configuration options start with reasonable
defaults, but applications have to customize
at least some of them. You can set all replication related configuration options
either programmatically or in the <a href="../api_reference/C/configuration_reference.html" class="olink">DB_CONFIG file</a>.
</p></li>
<li> Starting the application and replication
<p>
The <a href="../api_reference/C/db_replicate.html" class="olink">db_replicate utility</a> assumes that an
environment exists and that the application has run recovery,
if necessary, and created and configured the environment.
The startup flow of a typical TDS application may not be the
best flow for a replication application and you
must understand the issues involved.
For instance, if an application starts, runs recovery,
and performs update operations before starting the <a href="../api_reference/C/db_replicate.html" class="olink">db_replicate utility</a>,
then if that site becomes a client when replication starts,
those update operations will be rolled back.
</p></li>
<li> Handling events
<p>
Almost all of the replication-specific events are handled
by the <a href="../api_reference/C/db_replicate.html" class="olink">db_replicate utility</a> process, and therefore the application
process does not see them. If the application needs to know
the information from those replication-specific events, such as
role changes, the application must call the <a href="../api_reference/C/repstat.html" class="olink">rep_stat() method</a> method.
The one replication-specific event the application can now
receive is the <a href="../api_reference/C/envevent_notify.html#event_notify_DB_EVENT_REP_PERM_FAILED" class="olink">DB_EVENT_REP_PERM_FAILED</a> event.
See <a class="xref" href="rep_mgr_ack.html" title="Choosing a Replication Manager Ack Policy">Choosing a Replication Manager Ack Policy</a>
for additional information about this event.
</p></li>
<li> Handling errors
<p>
There are some error return values that relate only to replication.
Specifically, the <code class="literal">DB_REP_HANDLE_DEAD</code> error should now be handled
by the application. Also, if master leases are in use, then the
application also needs to consider the <code class="literal">DB_REP_LEASE_EXPIRED</code> error.
</p></li>
<li> Flexibility tradeoff
<p>
You are giving up flexibility
for the ease of use of the utility.
Application complexity or requirements may eventually
dictate integrating HA calls into the application
over using the <a href="../api_reference/C/db_replicate.html" class="olink">db_replicate utility</a>. </p></li>
<li> Read-only client application
<p>
The application requires additional changes to manage
the read-only status when the application takes on the role of
a client.
</p></li>
</ul>
</div>
</div>
<div class="sect2" lang="en" xml:lang="en">
<div class="titlepage">
<div>
<div>
<h3 class="title"><a id="id3868618"></a>Common Use Case</h3>
</div>
</div>
</div>
<p>
This section lists the steps needed to get replication running for
a common use case of the <a href="../api_reference/C/db_replicate.html" class="olink">db_replicate utility</a>.
The use case presented is an existing TDS application that
already has its environment and databases created and is up and running.
At some point, HA is considered because failover protection
or balancing the read load may now be desired.
</p>
<div class="orderedlist">
<ol type="1">
<li>
<p>
To understand the issues involved in a replication/HA application, see
the <a href="../api_reference/C/db_replicate.html" class="olink">db_replicate utility</a> section in the <span class="emphasis"><em>API Reference Guide</em></span>, the <a href="../api_reference/C/rep.html" class="olink">Replication Chapter</a> in the <span class="emphasis"><em>
Programmer's Reference Guide</em></span>, and the source code of the ex_rep_mgr
example program.
</p>
</li>
<li>
<p>
Make a local hot backup of the current
application environment to a new location to use as a testing area.
</p>
</li>
<li>
<p>
Add the <a href="../api_reference/C/envopen.html#envopen_DB_INIT_REP" class="olink">DB_INIT_REP</a> and <a href="../api_reference/C/dbopen.html#open_DB_THREAD" class="olink">DB_THREAD</a> flags (if not already
being used) to the application or the <a href="../api_reference/C/configuration_reference.html" class="olink">DB_CONFIG file</a>.
</p>
</li>
<li>
<p>
Modify the <a href="../api_reference/C/configuration_reference.html" class="olink">DB_CONFIG file</a> to add the necessary replication
configuration values. At a minimum, the local
host and port information must be added via the <a href="../api_reference/C/repmgrlocal_site.html" class="olink">repmgr_set_local_site() method</a>.
As more sites are added to the group, remote host and port
information must also be added via the <a href="../api_reference/C/repmgrremote_site.html" class="olink">repmgr_add_remote_site() method</a>.
</p>
</li>
<li>
<p>
Rebuild the application and restart
it in the current testing directory.
</p>
</li>
<li>
<p>
Start the <a href="../api_reference/C/db_replicate.html" class="olink">db_replicate utility</a> on the master site with the -M option and
any other options needed such as -h for the home directory.
At this point you have a lone master site running in an
environment with no other replicated sites in the group.
</p>
</li>
<li>
<p>
Optionally, prepare to start a client site by performing a
manual hot backup of the running master environment to
initialize a client target directory. While replication
can make its own copy, the hot backup will expedite the
synchronization process. Also, if the application assumes
the existence of a database and the client site is started
without data, the application may have errors or incorrectly
attempt to create the database.
</p>
</li>
<li>
<p>
Copy the application to the client target.
</p>
</li>
<li>
<p>
Modify the client environment's <a href="../api_reference/C/configuration_reference.html" class="olink">DB_CONFIG file</a> to set the client's local host and port values and to add
remote site information for the master site and any
other replication configuration choices necessary.
</p>
</li>
<li>
<p>
Start the application on the client. The client application
should not update data at this point, as explained previously.
</p>
</li>
<li>
<p>
Start the <a href="../api_reference/C/db_replicate.html" class="olink">db_replicate utility</a> specifying the
client environment's home directory using the -h option. Omit the -M
option in this case, because the utility defaults to
starting in the client role.
</p>
</li>
</ol>
</div>
<p>
Once the initial replication group is established, do not use the -M option with
the <a href="../api_reference/C/db_replicate.html" class="olink">db_replicate utility</a>.
After the initial start, <a href="../api_reference/C/db_replicate.html" class="olink">db_replicate utility</a> assumes the use of
elections. If a site crashes, it should rejoin the group as
a client so that it can synchronize with the rest of the group.
</p>
</div>
<div class="sect2" lang="en" xml:lang="en">
<div class="titlepage">
<div>
<div>
<h3 class="title"><a id="id3868784"></a>Avoiding Rollback</h3>
</div>
</div>
</div>
<p>
Depending on how an application is structured, transactional rollback
can occur. If this is possible, then you must make application
changes or be prepared for successful transactions to disappear.
Consider a common program flow where the application first creates
and opens the environment with recovery. Then, immediately after
that, the application opens up the databases it expects to use.
Often an application will use the <a href="../api_reference/C/dbopen.html#open_DB_CREATE" class="olink">DB_CREATE</a> flag so that if the
database does not exist it is created, otherwise the existing one is
used automatically. Then the application begins servicing transactions
to write and read data.
</p>
<p>
When replication is introduced, particularly via the <a href="../api_reference/C/db_replicate.html" class="olink">db_replicate utility</a>, the
possibility of rollback exists unless the application takes steps
to prevent it. In the situation described above, if all of the
above steps occur before the <a href="../api_reference/C/db_replicate.html" class="olink">db_replicate utility</a> process starts, and
the site is started as a client, then all the operations will be
rolled back when the site finds the master. The client site will
synchronize with the log and operations on the master site, so
any operations that occurred in the client application before it
knew it was a client will be discarded.
</p>
<p>
One way to reduce the possibility of rollback is to modify the
application so that it only performs update operations (including
creation of a database) if it is the master site. If the application
refrains from updating until it is the master, then it will not perform
operations when it is in the undefined state before replication
has been started.
The event indicating a site is master will be delivered to the
<a href="../api_reference/C/db_replicate.html" class="olink">db_replicate utility</a> process, so the application process must look
for that information via the <a href="../api_reference/C/repstat.html" class="olink">rep_stat() method</a>.
A site that is expecting to perform updates may need to poll
via the <a href="../api_reference/C/repstat.html" class="olink">rep_stat() method</a> to see the state change from an undefined
role to either the master or client role. Similarly, since a
client site cannot create a database, it may need to poll for
the database's existence while the client synchronizes with the master
until the database is created at the client site.
</p>
</div>
<div class="sect2" lang="en" xml:lang="en">
<div class="titlepage">
<div>
<div>
<h3 class="title"><a id="id3868880"></a>When to Consider an Integrated HA Application</h3>
</div>
</div>
</div>
<p>
The <a href="../api_reference/C/db_replicate.html" class="olink">db_replicate utility</a> provides the means to achieve
a replicated application quickly. However,
the trade-off for this rapid implementation is that the full
flexibility of replication is not available. Some applications
may eventually need to consider integrating directly with
replication rather than using the <a href="../api_reference/C/db_replicate.html" class="olink">db_replicate utility</a> if greater flexibility is desired.
</p>
<p>
One likely reason for considering integration would be the
convenience of receiving all replication-related events in
the application process and gaining direct knowledge of such
things as role changes.
Using the event callback is cleaner and easier than
polling for state changes via the <a href="../api_reference/C/repstat.html" class="olink">rep_stat() method</a>.
</p>
<p>
A second likely reason for integrating replication directly
into the application is the multi-process aspect of the
utility program. The developer may find it easier to insert
the start of replication directly into the code once the
environment is created, recovered, or opened, and avoid
the scenario where the application is running in the
undefined state. Also it may simply be easier to start
the application once than to coordinate different processes
and their startup order in the system.
</p>
</div>
</div>
<div class="navfooter">
<hr />
<table width="100%" summary="Navigation footer">
<tr>
<td width="40%" align="left"><a accesskey="p" href="rep_mgrmulti.html">Prev</a> </td>
<td width="20%" align="center">
<a accesskey="u" href="rep.html">Up</a>
</td>
<td width="40%" align="right"> <a accesskey="n" href="rep_mgr_ack.html">Next</a></td>
</tr>
<tr>
<td width="40%" align="left" valign="top">Running Replication Manager in multiple processes </td>
<td width="20%" align="center">
<a accesskey="h" href="index.html">Home</a>
</td>
<td width="40%" align="right" valign="top"> Choosing a Replication Manager Ack Policy</td>
</tr>
</table>
</div>
</body>
</html>
