Initializing a new site

By default, adding a new site to a replication group only requires the client to join. Berkeley DB will automatically perform internal initialization from the master to the client, bringing the client into sync with the master.

However, depending on the network and infrastructure, it can be advantageous in a few instances to use a “hot backup” to initialize a client into a replication group. Clients not wanting to automatically perform internal initialization should call the DB_ENV->rep_set_config() method to turn off the DB_REP_CONF_AUTOINIT flag. Turning off this configuration flag causes Berkeley DB to return DB_REP_JOIN_FAILURE to the application’s DB_ENV->rep_process_message() method instead of performing internal initialization.

To use a hot backup to initialize a client into a replication group, perform the following steps:

  1. Do an archival backup of the master’s environment, as described in Database and log file archival. The backup can either be a conventional backup or a hot backup.
  2. Copy the archival backup into a clean environment directory on the client.
  3. Run catastrophic recovery on the client’s new environment, as described in Recovery procedures.
  4. Reconfigure and reopen the environment as a client member of the replication group.

If copying the backup to the client takes a long time relative to the frequency with which log files are reclaimed using the db_archive utility or the DB_ENV->log_archive() method, it may be necessary to suppress log reclamation until the newly restarted client has “caught up” and applied all log records generated during its downtime.

As with any Berkeley DB application, the database environment must be in a consistent state at application startup. This is most easily assured by running recovery at startup time in one thread or process; it is harmless to do this on both clients and masters even when not strictly necessary.