Eloquence B.08.20 contact contact

Documentation / Eloquence Replication

Eloquence Replication



Related documents:


This feature allows to replicate database transactions to other database environments (local or remote). Replication is unidirectional and performed asynchronously. It is typically close to real-time if allowed by server performance and connection bandwidth.

On the master server, committed transactions are saved in Eloquence forward-log files. The dbrepl replication utility is used to transfer and apply committed transactions from the master to any replicated servers ("slave servers"). On the slave server(s), the databases are available for access in read-only mode.

replication block diagram

The Eloquence replication functionality is not specific to a database but performs a replication of all changes to a database environment. It does not perform regular database calls but replicates transaction results. This improves performance and allows covering any changes that are described by internal transactions, including administrative changes such as creation of databases, structural changes and restoring single databases. Technically, the replication function performs a continuous incremental forward recovery on slave servers of committed transactions. Consequently, any information that is not maintained by the database server is outside the scope of the Eloquence replication functions.

Expected use of this function includes load sharing (e.g. use a replicated environment for reporting), hot standby (allow switching users to a running server instance in case of a problem) and making replicated data available in branch offices that are connected through WAN lines.

To use Eloquence replication, an additional "repl" license key is required.


To use replication the following requirements must be met:

  • The slave function is only enabled if a specific (repl) license key is present. The repl license key must be present on any system used as replication slave. No repl license key is required on a master system as long as it is not used as a replication slave.
  • FwLog must be enabled on the master server; using EnableAudit=1 is suggested but optional (it is not required by the replication function). Enabling FwLog on the slave server is optional.
  • The master system needs sufficient disk space to hold any forward- log files that are not yet replicated to the slave servers entirely.
  • Replication master and slave must share the same architecture (same byte order and alignment, may depend on the CPU or operating system).
  • The Eloquence version on the master and slave may be different. Using a newer release on the slave system is always supported. Using a newer release on the master system is supported as long as no functionality is used that is not available in the earlier release (for example, encryption requires Eloquence version B.08.10 or above.


The Eloquence replication functions add new options for the server configuration file. The supplied default file /opt/eloquence/8.2/newconfig/config/eloqdb.cfg has been updated accordingly.

Role = Standalone | Master | Slave
RedirectWrite = server:service
IgnoreWrite = 0 | 1
TmpDir = /tmp

The Replication.Role configuration item defines the role of this server.
If not specified, it will default to Standalone. If set to Master this specifies a master server. If set to Slave this specifies a slave server.

Setting Role to Master has the effect that some operations that would result in replicated servers to become unsynchronized (such as bimport) are disallowed. It also causes the master server to write additional information on opened databases to the forward-log files, that allow the slave server to detect conflicts between replication and concurrent use.

Role must be set to Slave for a replicated server. If configured as a slave server, any write attempt is rejected (unless RedirectWrite or IgnoreWrite options are used) and the replication is enabled.

The RedirectWrite configuration item is only used on a slave server and may be used to specify the corresponding master server for a slave server. It specifies the server name or IP address and service name or port number, separated by a colon.
If RedirectWrite is defined on a slave server, some DBOPEN modes (modes 1, 3, and 4) are transparently redirected to the specified server (this will also add a note to the log file).

The IgnoreWrite configuration item is only used on a slave server. If set, opening a database in write mode on a slave server is accepted but internally converted into a read-only open mode. This way, a program that opens a database in write mode but only performs read operations may also run on a slave server.

Please note: If IgnoreWrite is set, RedirectWrite is implicitly disabled.

The TmpDir configuration item may be used on a slave server to specify a temporary directory that is used as a scratch storage for collecting and processing partial transaction information. It needs to provide sufficient disk space to hold the size of the largest transaction. It defaults to the /tmp directory.

Example configuration on a master server:

Role = Master

FwLog = /fwlog/fw-%N

A master server needs to enable forward-logging to files (managed by the server process) and should define a Role=Master.

Example configuration on a slave server:

Role = Slave
RedirectWrite =

A slave server needs to define Role=Slave and may define RedirectWrite to bounce DBOPEN calls in write mode to the master server.

Please note that the RedirectWrite configuration string (which may specify server or service by name) is resolved by the client library.

Also note that RedirectWrite only affects application programs using one of the dbopen modes 1, 3, or 4. Some database utilities, such dberase, use special dbopen modes and will fail when used with a slave server.

dbrepl utility

The Eloquence dbrepl utility is used to replicate committed transactions from a master server to a slave server. This utility needs to be run with dba or operator privileges.

As of Eloquence B.08.20 the dbrepl utility may be invoked manually or may be integrated with the Eloquence startup configuration, leveraging the same start/stop methods as the eloqdb server, including an optional automatic replication startup at system boot time.

Please refer to the dbrepl utility documentation for details.

dbctl utility

The dbctl utility may be used to obtain replication status information from a master or slave server. Output includes server role, forward-log status and most recently processed checkpoint. For a slave server it also shows whether replication is active or inactive, as well as details on the last replication activity and the estimated replication lag.

With dba or operator privileges, the dbctl utility may also be used for disconnecting an active replication session from a slave server.

Please refer to the dbctl utility documentation for details.

Starting (or re-synchronizing) a slave server

To setup a slave server, forward-logging needs to be configured on the master server.

Then a backup copy of the volume files of the master server is transferred to the slave environment. This could also be a previous backup if the forward-log files since this backup are present on the master server.

On the Slave server, the server config file needs to specify Replication.Role = Slave. The slave server needs to be started.

On the master server, run the dbrepl utility to start replicating any committed changes to the server. After some time the slave server should become current and follow the master server closely.

For a step-by-step checklist and a 7.10 demo session see:

Using forward-logging with a slave server

While the use of forward-logging is mandatory on the master server, it is optional on the slave server. If enabled, the slave server writes a replicated copy of the forward-logs in addition to maintaining the replicated copy of the databases. This may be helpful in disaster recovery or auditing situations; for example, when the master server is inaccessible.

In the eloqdb configuration file on a slave server, the only relevant parameter of the [ForwardLog] section is FwLog. Any other configuration parameters in the [ForwardLog] section (for example, FwMaxSize or EnableAudit) are ignored by the slave server because they are defined by the master server.

For slave server forward-logging, the FwLog parameter must be configured for automatic file management, that is, it must refer to a directory with sufficient disk space available and have the %N token in the filename part.
On the slave server, the sequence of the forward-log files equals the file sequence on the master server. In other words, all the information contained in the master forward-log files are copied to files with the same generation and sequence numbers on the slave server.

If a replication is suspended and later resumed, the slave server locates the last checkpoint in the existing forward-log files and continues to append new replication actions at that point. Therefore, in the end the slave server forward-log files will always equal the master server files.

The dbctl forwardlog interface allows to manually enable/disable forward- logging and to query the current forward-log status.

If forward-logging is disabled the slave server immediately stops to write to its forward-log files. Any information that is replicated after forward-logging was disabled will never be written to the slave server forward-log files (i.e., the forward-log is interrupted at that point).

The disabled state is retained until forward-logging is manually enabled or the slave server is restarted.

When forward-logging is manually enabled the slave server forward-log will typically not be written immediately. Instead, the slave server starts to write the forward-log when a new replication segment begins (i.e., when the master server begins a new forward-log segment).

Changing roles of master and slave servers

The following procedures should be used to switch roles of any replicated server:

  1. Stop the master server
  2. Make sure replication has synced the most recent transaction. If the dbrepl utility is not active you may want to consider running dbrepl with the -S option to make sure the most recent changes are replicated.
  3. Shutdown the slave server.
  4. Change the master and slave configuration files (change role from master to slave and vice versa) and restart the server processes. Please make sure the former slave server has forward-logging enabled.

This procedure ensures an orderly handover and allows to replicate changes from the new master server. In all other cases the new slave server must be re-synchronized from the new master server (see section above).

Using slave server volume files to recover the master

After the master server has failed, the recommended procedure is to change the role on the slave server to a master. This allows to continue with minimal interruption. The former master server is eventually recovered from the former slave server and updated by replication as described above.

However, if changing server roles is not desired it is also possible to recover the master server from the slave server with the procedure described below:

  1. Make sure the dbrepl utility is not active on the master server
  2. Remove the fwlog files from the master server (or move them to a backup directory). If the master has failed its content may not be consistent with the slave server.
  3. Copy the volume files from the slave server to the master server. The slave server may be running and on-line backup mode is not required.
  4. Start the master server process.
  5. Start dbrepl to replicate database changes to the slave.


Any modification to a database environment that is not described through transactions will have the effect that the replication gets out of sync and any slave servers need to be re-synchronized.

This may be the result of using Eloquence off-line support utilities that could affect the database content while the server process is not active, for example:

  • dbfsck (when used to perform database low level repairs)
  • dbcfix (when used to repair database chain linkage)

Disabling forward-logging on the master server for any reason (eg. due to lack of disk space or for administrative purposes) will have the effect that any slave servers need to be re-synchronized.

The Eloquence bimport function (for data migration) only partially uses transactions (only meta data are covered by transactions for performance reasons). Consequently, the bimport function may not be used on a master server (this function is disabled when configured as a master server) and its use would require re-synchronizing any slave servers.

Any configuration changes affecting the database volume files (e.g. adding a volume file or changing the volume file size limits) requires the same change to be applied to any replicated database environment. Future versions of the replication function should be able to detect this condition and stop replication unless the slave server is configured equivalently. However, the current release will result in an abort of the slave server.

In case the master server aborts (e.g. due to an internal problem or due to a system crash when SyncMode is enabled) the replication should usually be able to continue once the master server was restarted and recovered successfully. During startup the master server (or a dblogreset) would attempt to recover any possibly missing records from the transaction journal. If successful, the replication should be able to continue.

Modification of database content on a replicated server (slave server) is not allowed in any case. Using Eloquence off-line maintenance utilities (such as dbfsck in write mode) to modify the volume files content will either corrupt the slave environment or cause the replication to stop (and requires re-synchronization).

A recovery of the master server from backup (restoring the volume files from the backup and running dbrecover) could corrupt a replicated server state or cause replication to fail unless the forward recovery continues beyond the point the slave server was most recently synchronized with. For example, restoring a backup and running dbrecover on a partial set of forward-log files and then starting the master server would have this effect.

  Privacy | Webmaster | Terms of use | Impressum Revision:  2013-12-12  
  Copyright © 2006-2013 Marxmeier Software AG