The dbrepl utility reads the master server config file to obtain the location and naming convention of forward-log files. It then contacts the specified slave server and obtains the most recently synchronized checkpoint on the slave server. With this information the master server forward-log files are searched to locate a synchronization point. dbrepl then submits any enqueued transactions from this point to the slave server.

Once the slave server is up to date, any subsequently committed transactions should be replicated close to real-time, subject to communication bandwidth. Replication should only place minor load on the master and slave server once synchronization has been achieved.

As the dbrepl utility reads the master server forward-log files, it should run on the same system as the master server and requires read-only access rights to the forward-log files of the master server.

dbrepl [options] [slave_server_addr]

options:
 -help        - show usage (this list)
 -C cfg       - replication configuration file
 -D           - run dbrepl in background
 -P pid_file  - create pid file
 -c cfg       - master server configuration file
 -v           - verbose, display progress
 -u name      - user name (defaults to dba)
 -p pswd      - password
 -d flags     - debug flags
 -l logfile   - log file name (or console/syslog)
 -S           - synchronize on existing log, then exit
 -G           - process current log generation, then exit
 -b bps[k|m]  - limit bandwidth to bps [kilo|mega] bits per second
 -T timestamp - process until point in time (incl.)

timestamp formats:
 YYYY-MM-DD HH:MM:SS | MM/DD/YYYY HH:MM:SS | DD.MM.YYYY HH:MM:SS
 Any character may be used to separate date and time
 time is optional (defaults to 00:00:00)

The -c option is used to specify the master server config file. If not present, it defaults to the default config file on the local system (i.e. /etc/opt/eloquence/8.2/eloqdb.cfg for HP-UX and Linux).

The slave_server_addr command line argument specifies the slave server host name or IP address and service name or port number, separated by a colon (e.g. 194.64.71.28:8202). The host name or IP address may be omitted and defaults to localhost (127.0.0.1).

The EQ_DBSERVER environment variable may be used to specify the slave server address. The EQ_DBUSER (and EQ_DBPASSWORD) environment variables may be used as an alternative to the -u and -p options (to help preventing passwords from being recorded and visible in shell history or server log files).

By default, dbrepl synchronizes all enqueued changes and then closely follows any on-going changes on the master server.

• If the -S option is present, dbrepl exits once all enqueued changes are synchronized.
• If the -G option is present, dbrepl exits if the volume generation changes (eg. master server is restarted, on-line backup or "dbctl forwardlog restart" is run).
• If the -T option is present, dbrepl exits after processing all enqueued changes up to (and including) a given checkpoint date and time. The time defaults to 00:00:00 if not specified explicitly. Date and time can be separated by space or other characters, shell quoting might be required.

For example:

$ dbrepl -c eloqdb.cfg -v -S :8202
R1: processing forward-log file: /fwlog/fw-1-1
R1: found synchronization point with slave server
...
R1: processing forward-log file: /fwlog/fw-12-1
R1: slave server is up-to-date until 2006-04-18 18:54:17

The -b option may be used to limit the network bandwidth consumed by the replication. This throttling can be useful in case the network link between master and slave(s) is not dedicated to dbrepl and should not be saturated by the replication during high activity periods on the master. Note, however, that such throttling results in slave servers no longer being updated "as fast as possible".

The bandwidth limit is specified as bits, kilo bits (k suffix) or megabits (m suffix) per second. Any suffix must directly follow the value. For example: options "-b 2m" or "-b 2048k" or "-b 2097152" each specify a limit of 2 megabits per second, which is equivalent to 256 kilobytes per second.

To temporarily stop synchronization of a slave server, it is sufficient to stop the dbrepl utility. On next start dbrepl will continue from the previous point.

The -c option is used to specify the master server config file. If not present, it defaults to the default config file on the local system (i.e. /etc/opt/eloquence/8.2/eloqdb.cfg for HP-UX and Linux).

The -b option may be used to limit the network bandwidth consumed by the replication.

The -u and -p options may be used to specify the database user name and password. Alternatively, the EQ_DBUSER environment variable may be used.

The -v option enables additional log output.

The options -S, -G and -T may be used limit replication scope to enqueued changes, the current log generation or a point in time.

The option -l may be used to specify a log file. The log files "console" and "syslog" are special and result in log output to stderr and syslog.

The option -D is used on HP-UX and Linux to run the dbrepl process in the background. The option -P is used to create a pid file. These options are primarily intended for use by the start/stop script to manage dbrepl instances.

Database locks are not replicated between master and slave servers, i.e. DBLOCK calls issued on the master have no effect on the slaves and DBLOCK calls issued on a slave have no effect on the master.
This might cause applications behave differently when run on a slave server instead of the master server. For example, if a report uses DBLOCK calls to prevent certain data from being changed concurrently by other programs. On a slave server, the DBLOCK calls by the report program would not prevent dbrepl from applying concurrent database updates because dbrepl does not use IMAGE calls.

Information about databases opened for writing on the master is recorded in the forward-log files and thus available to dbrepl and the slave server. A slave server uses this information to prevent conflicting modes of access by suspending replication temporarily or by rejecting the conflicting DBOPEN attempts on the slave. For example:

• If a database is open in mode 8 on the slave server, replication is temporarily suspended as soon as the forward-log indicates a segment where the specific database was opened for writing on the master server. The slave resumes replication when the conflicting DBOPEN mode 8 ends.
  Please note that this suspended state does not only apply to the specific database, but to the slave server as a whole.

• If a dberase is replicated to the slave while the target database is still in use on the slave server, replication is temporarily suspended until the required exclusive access to this specific database is possible.
  Please note that this suspended state does not only apply to the specific database, but to the slave server as a whole.

• While replicating transactions that have been written on the master server using a DBOPEN in mode 3, the slave server will reject DBOPEN attempts for this specific database on the slave server.

# @(#) repl.cfg - B.08.20 ($Revision: 27.3 $)
#
# This file configures a replication instance and is read by dbrepl.
# Default location is the /etc/opt/eloquence/8.2 directory

# The master database config file
# Absolute path or relative to the Eloquence config directory
#master = eloqdb.cfg

# The slave server [host][:service]
#slave = localhost:eloqdb

# database credentials (may also reference a file)
#dbuser = dba
#dbpassword =

# syslog identity and facility
#sysident = dbrepl
#sysfacility = user

# specifies the log file (absolute path) or "syslog" to use syslog
# defaults to stderr when used interactively and syslog when used
# in background.
#logfile = syslog

# log flags, recommended is *1
#logflags = *0

# retry after connection failure (retry limit and delay in seconds)
#retrycnt = 0
#retrydelay = 300

# limit bandwidth to specified [kilo|mega] bits per second
# unit m (mega) or k (kilo) may be appended to the value
# for example, 10m specifies 10 million bits per second.
#bandwidthlimit = 0

Integration of replication in the start script (HP-UX and Linux)

A replication instance is configured as below:

REPL_CFG[0]=repl.cfg
REPL_START[0]=1
REPL_ID[0]="repl"

Replication Service on Windows

-install[:name] - install Windows service
-remove[:name]  - remove Windows service

The -install option may be followed by a dbrepl command line. If specified, the command line is saved in the registry and used whenever the service is started.

In the example below, a dbrepl service named "repl_prod" is installed using the -C command line option to specify the "repl_prod.cfg" config file:

dbrepl -install:repl_prod -C "C:\Program Files\Eloquence\8.2\etc\repl_prod.cfg"

The installed dbrepl service(s) may then be started using the Windows Services Control Panel or using the "net start" command, for example:

net start repl_prod

Before removing a dbrepl service the service must be stopped. The example uses the "net stop" command:

net stop repl_prod
dbrepl -remove:repl_prod