<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 <aclass="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 <ahref="../api_reference/C/db_replicate.html"class="olink">db_replicate</a> utility simplifies the use
of replication with a TDS application, you
must still understand replication and its impact on the application.
<p>Based on the terminology introduced in the <aclass="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 <ahref="../api_reference/C/db_replicate.html"class="olink">db_replicate</a> utility
is the "primary replication process".</p>
<p>
You must consider the following items when
planning to use the <ahref="../api_reference/C/db_replicate.html"class="olink">db_replicate</a> utility in combination with
a TDS application.
</p>
<divclass="itemizedlist">
<ultype="disc">
<li>Memory regions
<p>
The <ahref="../api_reference/C/db_replicate.html"class="olink">db_replicate</a> utility requires shared memory access among
separate processes, and therefore cannot be used with <ahref="../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 <aclass="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 <ahref="../api_reference/C/envopen.html#envopen_DB_INIT_REP"class="olink">DB_INIT_REP</a>
and <ahref="../api_reference/C/dbopen.html#open_DB_THREAD"class="olink">DB_THREAD</a> flags for the <ahref="../api_reference/C/envopen.html"class="olink">DB_ENV->open()</a> method.
Another required configuration item is the local address. You identify
this by creating a <ahref="../api_reference/C/db_site.html"class="olink">DB_SITE</a> handle and then setting the
<codeclass="literal">DB_LOCAL_SITE</code> parameter using the
<ahref="../api_reference/C/dbsite_set_config.html"class="olink">DB_SITE->set_config()</a> method. You also tell sites how to contact other
sites by creating <ahref="../api_reference/C/db_site.html"class="olink">DB_SITE</a> handles for those sites.
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 <ahref="../api_reference/C/configuration_reference.html"class="olink">DB_CONFIG</a> file.
</p></li>
<li> Starting the application and replication
<p>
The <ahref="../api_reference/C/db_replicate.html"class="olink">db_replicate</a> utility 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 <ahref="../api_reference/C/db_replicate.html"class="olink">db_replicate</a> utility,
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 <ahref="../api_reference/C/db_replicate.html"class="olink">db_replicate</a> utility 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 <ahref="../api_reference/C/repstat.html"class="olink">rep_stat()</a> method method.
The one replication-specific event the application can now
receive is the <ahref="../api_reference/C/envevent_notify.html#event_notify_DB_EVENT_REP_PERM_FAILED"class="olink">DB_EVENT_REP_PERM_FAILED</a> event.
See <aclass="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 <codeclass="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 <codeclass="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 <ahref="../api_reference/C/db_replicate.html"class="olink">db_replicate</a> utility. </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
This section lists the steps needed to get replication running for
a common use case of the <ahref="../api_reference/C/db_replicate.html"class="olink">db_replicate</a> utility.
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>
<divclass="orderedlist">
<oltype="1">
<li>
<p>
To understand the issues involved in a replication/HA application, see
the <ahref="../api_reference/C/db_replicate.html"class="olink">db_replicate</a> utility section in the <spanclass="emphasis"><em>API Reference Guide</em></span>, the <ahref="../api_reference/C/rep.html"class="olink">Replication Chapter</a> in the <spanclass="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 <ahref="../api_reference/C/envopen.html#envopen_DB_INIT_REP"class="olink">DB_INIT_REP</a> and <ahref="../api_reference/C/dbopen.html#open_DB_THREAD"class="olink">DB_THREAD</a> flags (if not already
being used) to the application or the <ahref="../api_reference/C/configuration_reference.html"class="olink">DB_CONFIG</a> file.
</p>
</li>
<li>
<p>
Modify the <ahref="../api_reference/C/configuration_reference.html"class="olink">DB_CONFIG</a> file to add the necessary replication
configuration values. At a minimum, the local
host and port information must be added using
the <ahref="../api_reference/C/repmgr_site_parameter.html"class="olink">repmgr_site</a> method parameter.
As more sites are added to the group, remote host and port
information can optionally also be added by adding
more <ahref="../api_reference/C/repmgr_site_parameter.html"class="olink">repmgr_site</a> method parameters to the <ahref="../api_reference/C/configuration_reference.html"class="olink">DB_CONFIG</a> file file.
</p>
</li>
<li>
<p>
Rebuild the application and restart
it in the current testing directory.
</p>
</li>
<li>
<p>
Start the <ahref="../api_reference/C/db_replicate.html"class="olink">db_replicate</a> utility 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 <ahref="../api_reference/C/configuration_reference.html"class="olink">DB_CONFIG</a> file 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 <ahref="../api_reference/C/db_replicate.html"class="olink">db_replicate</a> utility 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 <ahref="../api_reference/C/db_replicate.html"class="olink">db_replicate</a> utility.
After the initial start, <ahref="../api_reference/C/db_replicate.html"class="olink">db_replicate</a> utility 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.
The <ahref="../api_reference/C/db_replicate.html"class="olink">db_replicate</a> utility 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 <ahref="../api_reference/C/db_replicate.html"class="olink">db_replicate</a> utility 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 <ahref="../api_reference/C/repstat.html"class="olink">rep_stat()</a> method.
</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
