Each replicated database is replicated from a master to a slave version of that database. Initially there is no replication; a master database must be created before it can be replicated. The database may, of course, be empty when replication starts. On the other hand, replication does not need to be specified immediately after the database is created; it can be initiated at any time after the database is created.

Before you start replication, you must boot the master database and then copy the database to the slave location. To ensure that the master database is not modified between the time you start the file-system copy and the time you start replication, you must freeze the master database. Follow these steps to start replication:

1. Boot the database on the master system.
2. When you are ready to start replication, freeze the master database by calling the SYSCS_UTIL.SYSCS_FREEZE_DATABASE procedure, as shown in the following example:

   CallableStatement cs = conn.prepareCall
   ("CALL SYSCS_UTIL.SYSCS_FREEZE_DATABASE()");
   cs.execute();
   cs.close();

   This procedure ensures that all data pages and the log are written to disk, and blocks modifications to the database until replication has successfully started.
3. Copy the database to the slave location.
4. Start slave replication mode on the Derby instance that is acting as the slave for the database. To start slave replication, use the startSlave=true attribute and, optionally, the slaveHost=hostname and slavePort=portValue attributes. For example, for a database named wombat, you might use the following connection URL:

   jdbc:derby:wombat;startSlave=true
   

5. Start master replication mode on the Derby instance that is acting as the master for the database. To start replication, connect to the database on the master system using the startMaster=true attribute in conjunction with the slaveHost=hostname attribute (and, optionally, the slavePort=portValue attribute). For example, you might use the following connection URL:

   jdbc:derby:wombat;startMaster=true;slaveHost=myremotesystem
   

   A successful use of the startMaster=true attribute will also unfreeze the database.

   If any unlogged operations are running when the user specifies startMaster=true, the attempt to start the master fails and an error message appears. The message instructs the user to unfreeze the database to allow the operations to complete, and then to specify startMaster=true again.

See the Derby Reference Manual for details about these attributes.

After replication has been started, the slave is ready to receive logged operations from the master. The master can now continue to process transactions. From this point on, the master forwards all logged operations to the slave in chunks. The slave repeats these operations by applying the contents of the Derby transaction log, but does not process any other operations. Attempts to connect to the slave database are refused. In case of failure, the slave can recover to the state the master was in at the time the last chunk of the transaction log was sent.

While replication is running, neither the slave or the master database is permitted to be shut down. Replication must be stopped before you can shut down either the slave or the master database. There is one exception to this rule: if the entire system is shut down, the peer that is shut down notifies the other replication peer that replication is stopped.

If you install jar files on the master system while replication is running, the same jars are not automatically installed on the slave. But because the transaction log information sent to the slave system includes the jar file installation, the slave database has a record of the jar files, even though they are not actually there. Therefore, you must install the jar files on the former slave after a failover by calling either SQLJ.remove_jar followed by SQLJ.install_jar, or SQLJ.replace_jar. (For information on installing jar files, see "Storing jar files in a database" in the Derby Tools and Utilities Guide.)

If the jar files must be available to clients immediately after a failover, you must stop replication and then start replication over again from the beginning, so that the slave database will have the same jar files as the master.