Starting and running replication

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 shut down the master database and then copy the database to the slave location. Follow these steps to start replication:

Make sure that the database on the master system is shut down cleanly.
Copy the database to the slave location.
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
```
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 start the database.

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 "Loading classes from a database" in the Derby Developer's Guide and "System procedures for storing jar files in a database" in the Derby Reference Manual.)

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.