Configuring Failover

---

Specify the primary and alternate servers:
Specify your primary server using a connection URL or data source.
Specify one or multiple alternate servers by setting the AlternateServers property.

See "Specifying Primary and Alternate Servers".

NOTE: If using failover with an Oracle RAC, the primary server must be a primary node and any alternate server must be a secondary node.

Choose a failover method by setting the FailoverMode connection property. The default method is connection failover (FailoverMode=connect). See "Using Failover" for an overview of each failover method.
If FailoverMode=extended or FailoverMode=select, set the FailoverGranularity property to specify how you want the driver to behave if exceptions occur while trying to reestablish a lost connection. The default behavior of the driver is to continue with the failover process and post any exceptions on the statement on which they occur (FailoverGranularity=nonAtomic).
Optionally, configure the connection retry feature. See "Specifying Connection Retry".
Optionally, set the FailoverPreconnect property if you want the driver to establish a connection with the primary and an alternate server at the same time. The default behavior is to connect to an alternate server only when failover is caused by an unsuccessful connection attempt or a lost connection (FailoverPreconnect=false).

Specifying Primary and Alternate Servers

---

Connection information for primary and alternate servers can be specified using either one of the following methods:

Connection URL through the JDBC Driver Manager
JDBC data source

For example, the following connection URL for the Oracle driver specifies connection information for the primary and alternate servers using a connection URL:

jdbc:datadirect:oracle://server1:1521;ServiceName=TEST;User=test;
Password=secret;AlternateServers=(server2:1521;ServiceName=TEST2,
server3:1521;ServiceName=TEST3) 

In this example:

...server1:1521;ServiceName=TEST... 

is the part of the connection URL that specifies connection information for the primary server. Alternate servers are specified using the AlternateServers property. For example:

...;AlternateServers=(server2:1521;ServiceName=TEST2,
server3:1521;ServiceName=TEST3) 

Similarly, the same connection information for the primary and alternate servers specified using a JDBC data source would look like this:

OracleDataSource mds = new OracleDataSource(); 
mds.setDescription("My OracleDataSource"); 
mds.setServerName("server1"); 
mds.setPortNumber(1521); 
mds.setServiceName("TEST"); 
mds.setUser("test"); 
mds.setPassword("secret"); 
AlternateServers=(server2:1521;ServiceName=TEST2,
server3:1521;ServiceName=TEST3) 

In this example, connection information for the primary server is specified using the ServerName, PortNumber, and ServiceName properties. Connection information for alternate servers is specified using the AlternateServers property.

For information about specifying connection information for primary and alternate servers using a tnsnames.ora file, see "Using tnsnames.ora Files".

The value of the AlternateServers property is a string that has the format:

(servername1[:port1][;property=value[;...]][,servername2[:port2]
[;property=value[;...]]]...) 

where:

servername1 is the server name of the first alternate database server, servername2 is the server name of the second alternate database server, and so on. The server name is required for each alternate server entry.

port1 is the port number on which the first alternate database server is listening, port2 is the port number on which the second alternate database server is listening, and so on. The port number is optional for each alternate server entry. If unspecified, the port number specified for the primary server is used. If a port number is unspecified for the primary server, a default port number of 1521 is used.

property=value is one of the following connection properties: ServiceName or SID. These connection properties are optional for each alternate server entry and are mutually exclusive. For example:

jdbc:datadirect:oracle://server1:1521;ServiceName=TEST;User=test;
Password=secret;AlternateServers=(server2:1521;ServiceName=TEST2,
server3:1521) 

or

jdbc:datadirect:oracle://server1:1521;SID=ORCL;User=test;Password=secret;
AlternateServers=(server2:1521;SID=ORCL2,server3:1521) 

If you do not specify an optional connection property in an alternate server entry, the connection to that alternate server uses the property specified for the primary server. For example, if you specify SID=ORCL for the primary server, but do not specify a SID in the alternate server entry as shown in the following URL, the driver uses the SID specified for the primary server and tries to connect to the ORCL database on the alternate server:

jdbc:datadirect:oracle://server1:1521;SID=ORCL;User=test;Password=secret;
AlternateServers=(server2:1521,server3:1521) 

Specifying Connection Retry

---

Connection retry allows the Oracle driver to retry connections to the primary database server, and if specified, alternate servers until a successful connection is established. You use the ConnectionRetryCount and ConnectionRetryDelay properties to enable and control how connection retry works. For example:

jdbc:datadirect:oracle://server1:1521;ServiceName=TEST;User=test;
Password=secret;AlternateServers=(server2:1521;ServiceName=TEST2,
server3:1521;ServiceName=TEST3);ConnectionRetryCount=2;
ConnectionRetryDelay=5 

In this example, if a successful connection is not established on the Oracle driver’s first pass through the list of database servers (primary and alternate), the driver retries the list of servers in the same sequence twice (ConnectionRetryCount=2). Because the connection retry delay has been set to five seconds (ConnectionRetryDelay=5), the driver waits five seconds between retry passes.

Failover Properties

---

Table 6-6 summarizes the connection properties that control how failover works with the Oracle driver. See Table 6-1 for details about configuring each property.

Table 6-6. Summary: Failover Properties for the Oracle Driver 

Property	Characteristic
AlternateServers	One or multiple alternate database servers. An IP address or server name identifying each server is required. Port number and the ServiceName or SID connection properties are optional. If the port number is unspecified, the port specified for the primary server is used. If a port number is not specified for the primary server, the default port number of 1521 is used.
ConnectionRetryCount	Number of times the driver retries the primary database server, and if specified, alternate servers until a successful connection is established. The default is 5.
ConnectionRetryDelay	Wait interval, in seconds, between connection retry attempts when the ConnectionRetryCount property is set to a positive integer. The default is 1.
FailoverGranularity	Determines whether the driver fails the entire failover process or continues with the process if exceptions occur while trying to reestablish a lost connection. The default is nonAtomic (the driver continues with the failover process and posts any exceptions on the statement on which they occur).
FailoverMode	The failover method you want the driver to use. The default is connect (connection failover is used).
FailoverPreconnect	Specifies whether the driver tries to connect to the primary and an alternate server at the same time. The default is false (the driver tries to connect to an alternate server only when failover is caused by an unsuccessful connection attempt or a lost connection).
LoadBalancing	Sets whether the driver will use client load balancing in its attempts to connect to the database servers (primary and alternate). If client load balancing is enabled, the driver uses a random pattern instead of a sequential pattern in its attempts to connect. The default is false (client load balancing is disabled).
PortNumber	Port listening for connections on the primary database server. This property is supported only for data source connections. The default is 1521.
ServerName	IP address or server name of primary database server. This property is supported only for data source connections.
ServiceName	Database service name that specifies the database used for the connection. This property is mutually exclusive with the SID property.
SID	Oracle System Identifier that refers to the instance of the Oracle database running on the server. The default is ORCL. This property is mutually exclusive with the ServiceName property.

See "Using Failover" and "Using Client Load Balancing" for overviews of failover and client load balancing.