ToC path:

eXtremeDB HA Applications

Two-layered architecture

eXtremeDB High Availability uses a two-layered architecture that facilitates the development of HA-enabled eXtremeDB-based applications. The higher layer is called the protocol layer. This layer is responsible for the high availability logic of the application. The lower layer is called the transport or network layer which implements the actual transmission of data between the master and replica nodes.

Applications use the higher layer protocol API to implement high availability. The protocol layer uses the transport layer API to send and receive data between network nodes so that application developers normally do not need to interact with the lower level API. Only if implementing a custom transport layer will the developer be concerned with these lower layer functions.

Application structure

Several host language APIs are provided to incorporate eXtremeDB High Availability functionality. The C/C++, Java and C# APIs are described below. It is also possible to use xSQL to act as an HA master or replica application. (For more information and instructions on using the xSQL please refer to the xSQL User's Guide.)

To incorporate eXtremeDB High Availability:

C / C++

To incorporate eXtremeDB High Availability, C/C++ applications need to do the following:

1. Include mcoha.h into the application sources

2. Declare an auto_oid in the database schema

3. Link with two libraries that implement the protocol layer (HA) and the transport layer (NW)

4. Link with the serialization library libmcoseri.a or libmcoseri_debug.a.

The protocol layer is implemented in the mcoha library (libmcoha.a for Unix, mcoha.lib for Windows), and the platform-independent transport layer is implemented in a library with the name mconwXXX (libmconwXXX.a for Unix, mconwXXX.lib for Windows) where the “XXX” indicates the type of network protocol used. And more than one transport layer library may be linked with a single eXtremeDB High Availability application.

The following network transport layer protocols are provided with eXtremeDB High Availability:

TCP: libmconwtcp.a for Unix, mconwtcp.lib for Windows

UDP: libmconwudp.a for Unix, mconwudp.lib for Windows

Named Pipes: libmconwpipes.a for Unix, mconwpipes.lib for Windows

QNX Messaging: libmconwqnxm.a (only for QNX OS).

To initialize eXtremeDB High Availability, all C and C++ applications must call mco_HA_start() to start the HA runtime and mco_HA_channel_implementation_add() to register one or more NW channels. For example
 
    ...
    mco_runtime_start();
    mco_HA_start();
    mco_HA_channel_implementation_add(mco_nw_tcpip_vt());
    ...
     
C#

To incorporate eXtremeDB High Availability, C# applications need to:

1. Include the eXtremeDB namespace (using ExtremeDB;) in application sources

2. Set the HighAvailabilitySupport flag in the constructor of Database object to cause the HA support library to be dynamically loaded

Java

To incorporate eXtremeDB High Availability, Java applications need to:

1. Include the eXtremeDB namespace (import com.mcobject.extremedb.*;) in application sources

2. Set the HighAvailabilitySupport flag in the constructor of Database object to cause the HA support library to be dynamically loaded

Replication Data flow

The following diagram illustrates the basic eXtremeDB High Availability application data flow:

eXtremeDB High Availability applications may use synchronous or asynchronous replication and will normally implement hot switch logic where the master and replica will be copies of the same application, aware that they are operating as master or replica, with the replica able to switch roles if necessary. All of the replication functionality is managed internally by the eXtremeDB High Availability runtime, though additional custom processing can be implemented in replicas by responding to specific replication events.

The eXtremeDB High Availability runtime does the initial synchronization in the master application during the C/C++ function mco_HA_attach_replica(), in C# or Java applications the MasterConnection.AttachReplica() method, and in replicas during the C/C++ function mco_HA_attach_master(), in C# or Java applications the ReplicaConnection.AttachMaster() method. After the initial synchronization, replication is managed synchronously or asynchronously by the eXtremeDB High Availability runtime when the master calls the C function mco_trans_commit(), in C# or Java applications the MasterConnection.CommitTransaction() method.

The management of the communications channel operations inside, asynchronous buffer processing and other important internal functions within the eXtremeDB High Availability runtime are controlled by timeout values set in C application in the mco_HA_master_param_t structure values passed to function mco_HA_set_master_params() and the mco_HA_replica_param_t structure values passed to function mco_HA_attach_master(). In C# and Java applications these timeouts values are properties of the MasterConnection.Parameters and ReplicaConnection.Parameters classes and are set in the master by calling the MasterConnection.SetReplicationMode() method; in replicas by the ReplicaConnection.AtachMaster() method.

DDL requirements

The schema for a C/C++ application using a database that might be replicated in HA mode must include the auto_oid declaration.
     
    declare auto_oid [100000];
     
In C# and Java applications the auto_oid implementation is automatic when a database instance is created by invoking the Database class constructor with High Availability support. In C# this is done as follows:
     
    Database db = new Database( …, Database.Mode.HighAvailabilitySupport);
     
In Java the MCO_CFG_HA_SUPPORT flag is specified as follows:
     
    Database db = new Database( Database.MCO_CFG_HA_SUPPORT );
 

Whether the database actually participates in the HA synchronization is determined at run-time. When the data definition is compiled for HA, the eXtremeDB High Availability DDL compiler inserts an 8-byte unique identifier (called auto_OID, not to be confused with the field type autoid) into each object. This auto_OID is used by the runtime in the standby application to perform a synchronized commit outside the master application’s address space. Think of it as a global object identifier. A hash index is maintained for it, so the replica runtime can locate objects quickly when necessary.

(These implementation details are provided for information value only. There is no published interface to access the index).

Initial Synchronization

The first step in replication is initial synchronization which is managed by the eXtremeDB High Availability runtime. On the master side this happens in C/C++ applications when the function mco_HA_attach_replica() is called; in C# and Java applications the MasterConnection.AttachReplica() method. In the replica initial synchronization happens during its call to the C/C++ function mco_HA_attach_master() or the C# or Java ReplicaConnection.AttachMaster() method.

There are four ways to initially synchronize all newly attached replicas: static, hot, with BSE and stateful. The differences between these modes are described in the Synchronization page. In C/C++ applications, the master application chooses the mode by setting mode_flags element in the mco_HA_master_params_t structure. In C# and Java applications the mode is set in the MasterConnection.Parameters passed to the MasterConnection.SetReplicationMode() method.

Note that though it is not possible to combine the static and hot modes, other modes can be combined.