#include <db_cxx.h> int DbEnv::rep_set_config(u_int32_t which, int onoff);
The DbEnv::rep_set_config() method configures the Berkeley DB
replication subsystem.
The database environment's replication subsystem may also be configured using the environment's DB_CONFIG file. The syntax of the entry in that file is a single line with the string "rep_set_config", one or more whitespace characters, and the method which parameter as a string and optionally one or more whitespace characters, and the string "on" or "off". If the optional string is omitted, the default is "on"; for example, "rep_set_config DB_REP_CONF_NOWAIT" or "rep_set_config DB_REP_CONF_NOWAIT on". Because the DB_CONFIG file is read when the database environment is opened, it will silently overrule configuration done before that time.
The DbEnv::rep_set_config() method configures a database
environment, not only operations performed using the specified
DbEnv handle.
The DbEnv::rep_set_config() method may not be
called to set in-memory replication after the environment is
opened using the
DbEnv::open()
method.
This method should not be called to set preferred master mode or
master leases after the
DbEnv::rep_start()
or
DbEnv::repmgr_start()
methods
are called. For all other which
parameters, this method may be called at any time during the life
of the application.
The DbEnv::rep_set_config()
method either returns a non-zero error value or throws an
exception that encapsulates a non-zero error value on
failure, and returns 0 on success.
The which parameter must be set to one of the following values:
The replication master will automatically re-initialize outdated clients. This option is turned on by default.
The replication master sends groups of records to the clients in a single network transfer.
The client should delay synchronizing to a newly declared master. Clients configured in this way will remain unsynchronized until the application calls the DbEnv::rep_sync() method.
Store internal replication information in memory only.
By default, replication creates files in the environment home directory to preserve some internal information. If this configuration flag is turned on, replication only stores this internal information in-memory and cannot keep persistent state across a site crash or reboot. This results in the following limitations:
A master site should not reappoint itself master immediately after crashing or rebooting because the application would incur a slightly higher risk of client crashes. The former master site should rejoin the replication group as a client. The application should either hold an election or appoint a different site to be the next master.
An application has a slightly higher risk that elections will fail or be unable to complete. Calling additional elections should eventually yield a winner.
An application has a slight risk that the wrong site may win an election, resulting in the loss of some data. This is consistent with the general loss of data durability when running in-memory.
Replication Manager applications do not maintain group membership information persistently on-disk. For more information, see Managing Replication Files in the Berkeley DB Programmer's Reference Guide.
This configuration flag can only be turned on before the environment is opened with the DbEnv::open() method. Its value cannot be changed while the environment is open. All sites in the replication group should have the same value for this configuration flag.
DB_REP_CONF_LEASE
Master leases will be used for this site.
Configuring this option may result in
DB_REP_LEASE_EXPIRED error returns
from the
Db::get()
and
Dbc::get()
methods
when attempting to read entries from a database after the site's
master lease has expired.
This configuration flag may not be set after the DbEnv::repmgr_start() method or the DbEnv::rep_start() method is called. All sites in the replication group should have the same value for this configuration flag.
Berkeley DB method calls that would normally block while clients are in recovery will return errors immediately.
Replication Manager automatically runs elections to choose a new master when the old master fails or becomes disconnected. This option is turned on by default. In preferred master mode, this option cannot be turned off.
If this option is turned off, the application is
responsible for assigning the new master
explicitly, by calling the
DB_ENV->repmgr_start()
method.
Most Replication Manager applications should accept the default automatic behavior. Allowing two sites in a replication group to act as master simultaneously can lead to loss of data.
In an application with multiple processes per database environment, only the replication process may change this configuration setting.
By default, write operations cannot be performed on a replication client site. This option enables forwarding of simple client put and delete operations to the master site for processing. These operations must use an implicit NULL transaction ID to be forwarded. Any other write operation that specifies a non-NULL transaction or uses a cursor throws a DatabaseException. This option is turned off by default.
The master must have an open database handle for the database on which a forwarded write operation is being performed. All sites in the replication group should have the same value for this configuration option. (See the Configuring for Write Forwarding section in the Berkeley DB Programmer's Reference Guide for more information.)
This is the client site in a two-site replication group running in preferred master mode. This site automatically takes over as temporary master when the preferred master site is unavailable. Transactions committed on this site when it is operating as the temporary master may be rolled back if they conflict with preferred master transactions. (See the Preferred master mode section in the Berkeley DB Programmer's Reference Guide for more information.) This configuration flag may not be set after the DbEnv::repmgr_start() method is called.
The other site in the replication group should
be specified as the preferred master site using the
DB_REPMGR_CONF_PREFMAS_MASTER
configuration flag.
This is the preferred master site in a two-site replication group running in preferred master mode. This site functions as the master whenever its availability permits. When this site returns to the replication group after having been unavailable, it synchronizes with the temporary master and then automatically takes over as master. Transactions committed on this site will not be rolled back. (See the Preferred master mode section in the Berkeley DB Programmer's Reference Guide for more information.) This configuration flag may not be set after the DbEnv::repmgr_start() method is called.
The other site in the replication group should
be specified as the preferred master client site
using the
DB_REPMGR_CONF_PREFMAS_CLIENT
configuration flag.
Replication Manager observes the strict "majority" rule in managing elections, even in a replication group with only two sites. This means the client in a two-site replication group will be unable to take over as master if the original master fails or becomes disconnected. (See the Special considerations for two-site replication groups section in the Berkeley DB Programmer's Reference Guide for more information.) Both sites in the replication group should have the same value for this configuration flag. This option is turned on by default. In preferred master mode, this option cannot be turned off.
Epoll will be used for network input/output event notification for this site. Epoll should be used on Linux if the number of sites in the replication group is more than 1000.
Note that, Epoll is available only on a Linux environment, and if you try to enable this flag on other platforms, it would result in error 3727 - "DB_ENV->rep_set_config: cannot use EPOLL on this system. OS support not available for epoll()".
Poll will not be used for network input/output event notification for this site.
If the system call poll() is not available on the target platform, and you try to set this flag, it would result in error 3728 - "DB_ENV->rep_set_config: POLL support not available on this system. Ignoring this flag".
Secure Sockets Layer (SSL) will not be used for securing messages for the replication manager on this replication site.
The DbEnv::rep_set_config()
method may fail and throw a DbException
exception, encapsulating one of the following non-zero errors, or return one
of the following non-zero errors:
If setting in-memory replication after the database environment is already opened; if setting preferred master or master leases after replication is started; if setting a Replication Manager configuration flag for a Base API application; or if an invalid flag value or parameter was specified.