failover=true attribute

The failover=true attribute stops database replication on the slave system and converts the slave database into a normal database.

If you specify the failover=true attribute on the master, the attribute sends the remaining log records to the slave instance and then sends a failover message to the slave. The replication functionality and the database are then shut down on the master system. If failover is successful, an exception with the error code XRE20 is thrown. Hence, when issued on the master, the failover=true attribute does not return a valid connection.

You may specify this attribute on the slave only if the network connection between the master and the slave is down.

When you specify this attribute on the slave, or when a failover message is sent as part of the execution of the failover=true attribute on the master, all transaction log chunks that have been received from the master are written to disk. The slave replication functionality is shut down, and the boot process of the database is allowed to complete. The database is now in a transaction consistent state, reflecting all transactions whose commit log records were received from the master. When issued on the slave, the failover=true command returns a valid connection.

The Derby instance where this command is issued must be serving the named database in replication mode.

For more information, see the topics under "Replicating databases" in the Derby Server and Administration Guide.

Combining with other attributes

You must specify a database name in the connection URL, either in the subprotocol or by using the databaseName=nameofDatabase attribute.

If authentication is turned on, you must also specify this attribute in conjunction with the user=userName and password=userPassword attributes. Authorization for the master database cannot be checked when the network connection is down, so the requirement that the user must be the database owner is not enforced.

You may not specify this attribute in conjunction with any attributes not mentioned in this section.

Examples

-- start failover from master using database name in subprotocol,
--   authorization
jdbc:derby:myDB;failover=true;user=mary;password=little88lamb
-- start failover using databaseName attribute, no security
jdbc:derby:;databaseName=myDB;failover=true;