# Replicating databases

Replication is an important feature of a robust database management system. In Derby, you start database replication by using connection URL attributes.

The replication capability of Derby has the following features:

- One master, one slave: A replicated database resides in two locations and is managed by two different Derby instances. One of these Derby instances has the master role for this database, and the other has the slave role. Typically, the master and slave run on different nodes, but this is not a requirement. Together, the master and its associated slave represent a replication pair.
- Roll-forward shipped log: Replication is based on shipping the Derby transaction log from the master to the slave, and then rolling forward the operations described in the log to the slave database.
- Asymmetry: Only the master processes transactions. The slave processes no transactions, not even read operations.
- Asynchronicity: Transactions are committed on the master without waiting for the slave. The shipping of the transaction log to the slave is performed regularly, and is completely decoupled from the transaction execution at the master. This may lead to a few lost transactions if the master crashes.
- Shared nothing: Apart from the network line, no hardware is assumed to be shared.
- Replication granularity: The granularity for replication is exactly one database. However, one Derby instance may have different roles for different databases. For example, one Derby instance may have the following roles, all at the same time:
  - The master role for one database D1 replicated to one node
  - The slave role for a database D2 replicated from another node
  - The normal, non-replicated, role for a database D3

Replication builds on Derby's ability to recover from a crash by starting with a backup and rolling forward Derby's transaction log files. The master sends log records to the slave using a network connection. The slave then writes these log records to its local log and redoes them.

If the master fails, the slave completes the recovery by redoing the log that has not already been processed. The state of the slave after this recovery is close to the state the master had when it crashed. However, some of the last transactions performed on the master may not have been sent to the slave and may therefore not be reflected. When the slave has completed the recovery work, it is transformed into a normal Derby instance that is ready to process transactions. For more details, see Forcing a failover and Replication and security.

Several Derby properties allow you to specify the size of the replication log buffers and the intervals between log shipments, as well as whether replication messages are logged. See the Derby Reference Manual for details.

You can perform replication on a database that runs in either embedded mode or Network Server mode.

- Starting and running replication
  Each replicated database is replicated from a master to a slave version of that database.
- Stopping replication
  To stop replication of a database, connect to the master database using the stopMaster=true connection URL attribute.
- Forcing a failover
  At any time, you can transform the Derby database that has the slave role into a normal Derby database that can process transactions. This transformation from being a slave to becoming an active Derby database is called failover.
- Replication and security
  If you want to perform replication with the security manager enabled, you must modify the security policy file on both the master and slave systems to allow the master-slave network connection.
- Replication failure handling
  Replication can encounter several failure situations. The following table lists these situations and describes the actions that Derby takes as a result.

Parent topic: Part Two: Derby Administration Guide
Related concepts
Maintaining database integrity
Checking database consistency
Backing up and restoring databases
Importing and exporting data
Logging on a separate device
Obtaining locking information
Reclaiming unused space