| |
The dbrepl utility is used to replicate committed database transactions
from a master server to a slave server. This utility needs to be run with
dba or operator privileges.
The dbrepl utility reads the master server config file to obtain the
location and naming convention of forward-log files. It then contacts the
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 a 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 option -C may be used to specify a replication config file
that defines replication parameters. In this case any additional
arguments are optional and may be used to temporarily replace settings
in the configuration file.
If the -C option is not specified any replication parameters and
the slave server must be specified on the command line.
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 options are:
- -help
- The -help option displays a brief help text.
- -c eloqdb.cfg
- The -c option may be used to specify the master server
config file. If not present, the default eloqdb.cfg config file is used.
- -v
- The -v option enables additional log output.
- -u user
-p password
- The -u and -p options may be used to specify the
database user name and password when connecting to the slave
server. Alternatively, the EQ_DBUSER (and/or the
EQ_DBPASSWORD) environment variable may be used to
specify the credentials. The user defaults to dba.
Please note that a database user with operator or dba capabilities
is required.
- -S
-G
-T timestamp
- The options -S, -G and -T may be used limit
replication scope to enqueued changes, the current log generation
or a point in time.
- -l logfile
- 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.
- -b bps
- The -b option may be used to limit the network bandwidth consumed
by the replication.
- -D
- The option -D is used on HP-UX and Linux to run the dbrepl
process in the background.
This option is primarily intended for use by the start/stop script to
manage dbrepl instances.
- -P pidfile
- The option -P is used to create a PID file.
This option is primarily intended for use by the start/stop script to
manage dbrepl instances.
- -d flags
- The -d option specifies debug flags and is normally not used.
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 (e.g. 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.
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: The 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.
-
Beginning with Eloquence B.08.20 the dbrepl process may be started from the
command line to override selected options, but is typically controlled by a
platform specific init script on HP-UX and Linux (or run as Windows service)
to also allow integrating with system boot and shutdown.
-
To temporarily stop synchronization of a slave server, it is sufficient
to stop (or kill) the dbrepl utility. On the next start dbrepl will
continue from the previous point.
-
Please note that volume file operations outside transaction context, like dbvolextend
or write mode of dbrepack, dbfsck or dbcfix make subsequent use of dbrepl impossible
until the slave server(s) have been re-synchronized from a new baseline backup of the
volume files on the master server.
-
The exit codes issued by dbrepl are:
-
0 - successful execution, graceful exit
-
(will only be issued if the -S or -G command line option is
used and dbrepl executed normally until the existing log or
the current generation has been processed)
-
1 - failure, typically requires manual intervention
-
(for example, a configuration problem on the replication
master or slave servers)
-
2 - invalid or -help command line option
-
(the command line usage was output)
-
3 - connection problem
-
(could not connect or lost the connection to the replication
slave server)
Exit code 3 may be used in a script to retry the dbrepl invocation.
Preferably, repeated invocations should be appropriately delayed,
for example by sleeping 60 seconds between two invocations.
The example below uses the configuration repl.cfg to specify the
replication parameters. The command line argument -S causes dbrepl
to exit once the slave server is in sync.
$ dbrepl -C repl.cfg -v -S
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
dbrepl utility (B.08.20 release notes)
Database replication
(documentation)
dbrepl config file
|
|
