| |
The dbrepl utility is used to replicate committed database transactions
from a primary server to a secondary server. This utility needs to be run with
dba or operator privileges.
The dbrepl utility reads the primary server config file to obtain the
location and naming convention of forward-log files. It then contacts the
secondary server and obtains the most recently synchronized checkpoint
on the secondary server. With this information the primary server forward-log files
are searched to locate a synchronization point. dbrepl then submits any enqueued
transactions from this point to the secondary server.
Once the secondary 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 primary and secondary server once
synchronization has been achieved.
As the dbrepl utility reads the primary server forward-log files, it should run
on the same system as the primary server and requires read-only access rights to
the forward-log files of the primary server.
dbrepl [options] [secondary_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 - primary 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
-Z - enable compression
-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 secondary server must be specified on the command line.
The secondary_server_addr command line argument specifies the secondary 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 primary 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 secondary
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.
- -Z
- If the -Z option is present, traffic to the secondary is sent compressed.
This will reduce the replication bandwidth but will use additional CPU resources.
It depends on the network speed if this benefits replication performance.
- -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
secondary 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 primary 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. primary 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 primary and secondary(s) is not dedicated to dbrepl and should
not be saturated by the replication during high activity periods on
the primary. Note, however, that such throttling results in secondary
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.
-
As of B.08.40 the designation of replicated servers and roles was
updated. A master server is now described as primary server and a
former slave server is now described as a secondary server or a
replicated server.
This affects any messages and configuration options. Any previous
config files are fully compatible.
-
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 secondary 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 secondary server(s) have been re-synchronized from a new baseline backup of the
volume files on the primary 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
primary or secondary server)
-
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
secondary 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 secondary server is in sync.
$ dbrepl -C repl.cfg -v -S
R1: processing forward-log file: /fwlog/fw-1-1
R1: found synchronization point with secondary server
...
R1: processing forward-log file: /fwlog/fw-12-1
R1: secondary 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
|
|
