Library Version 12.1.6.1

Running Replication Manager in multiple processes
Prev | Chapter 12. Berkeley DB Replication | Next

## Running Replication Manager in multiple processes

Replication Manager supports shared access to a database environment from multiple processes or environment handles.

### One replication process and multiple subordinate processes

Each site in a replication group has just one network address (TCP/IP host name and port number). This means that only one process can accept incoming connections. At least one application process must invoke the DB_ENV->repmgr_start() method to initiate communications and management of the replication state. This is called the replication process. That is, the replication process is the Replication Manager process that is responsible for initiating and processing most replication messages.

If it is convenient, multiple processes may issue calls to the Replication Manager configuration methods, and multiple processes may call DB_ENV->repmgr_start(). Replication Manager automatically opens the TCP/IP listening socket in the first process to do so, and so this becomes the replication process. Replication Manager ignores this step in any subsequent processes, called subordinate processes.

If the replication process quits and there are one or more subordinate processes available, one subordinate process will automatically take over as the replication process. During an automatic takeover on the master site, the rest of the replication group briefly delays elections to prevent an unnecessary change of master. Automatic takeover does not occur if the replication process fails unexpectedly. Automatic takeover is most reliable when the DB_REP_ACK_TIMEOUT is the same value on all sites in the replication group.

### Persistence of local site network address configuration

The local site network address is stored in shared memory, and remains intact even when (all) processes close their environment handles gracefully and terminate. A process which opens an environment handle without running recovery automatically inherits the existing local site network address configuration. Such a process may not change the local site address (although it is allowed to redundantly specify a local site configuration matching that which is already in effect).

In order to change the local site network address, the application must run recovery. The application can then specify a new local site address before restarting Replication Manager. The application should also remove the old local site address from the replication group if it is no longer needed.

### Programming considerations

Note that Replication Manager applications must follow all the usual rules for Berkeley DB multi-threaded and/or multi-process applications, such as ensuring that the recovery operation occurs single-threaded, only once, before any other thread or processes operate in the environment. Since Replication Manager creates its own background threads which operate on the environment, all environment handles must be opened with the DB_THREAD flag, even if the application is otherwise single-threaded per process.

At the replication master site, each Replication Manager process opens outgoing TCP/IP connections to all clients in the replication group. It uses these direct connections to send to clients any log records resulting from update transactions that the process executes. But all other replication activity —message processing, elections, etc.— takes place only in the "replication process".

Replication Manager notifies the application of certain events, using the callback function configured with the DB_ENV->set_event_notify() method. These notifications occur only in the process where the event itself occurred. Generally this means that most notifications occur only in the replication process. Currently there are only two replication notification that can occur in a subordinate process:

1. DB_EVENT_REP_PERM_FAILED.

2. DB_EVENT_REP_AUTOTAKEOVER_FAILED

It is not supported for a process running Replication Manager to spawn a subprocess. In an application where a parent process spawns child subprocesses, Replication Manager can only run in the spawned child subprocesses. The following operations do not run Replication Manager and can safely be performed in the parent process: opening or closing an environment handle, running DB_ENV->failchk(), running recovery. The following operations can implicitly run a Replication Manager thread and should only be performed in a child subprocess: opening or closing a database handle, transactions, gets, puts, checkpoints.

If your application is a group of related processes managed by a single "watcher" process (as described in Architecting Transactional Data Store applications), the "watcher" process is the parent process and is subject to the same restrictions.

### Handling failure

Multi-process Replication Manager applications should handle failures in a manner consistent with the rules described in Handling failure in Transactional Data Store applications. To summarize, there are two ways to handle failure of a process:

- The simple way is to kill all remaining processes, run recovery, and then restart all processes from the beginning. But this can be a bit drastic.

- Using the DB_ENV->failchk() method, it is sometimes possible to leave surviving processes running, and just restart the failed process.

  Multi-process Replication Manager applications using this technique must start a new process when an old process fails. A subordinate process cannot automatically take over as the replication process if the previous replication process failed. If the failed process happens to be the replication process, then after a `failchk()` call, the next process to call DB_ENV->repmgr_start() will become the new replication process.

### Other miscellaneous rules

1. A database environment may not be shared between a Replication Manager application process and a Base API application process.

2. It is not possible to run multiple Replication Manager processes during mixed-version live upgrades from Berkeley DB versions prior to 4.8.

Prev | Up | Next
Managing replication directories and files | Home | Running replication using the db_replicate utility