Configuring Failover-Related Options

The following table summarizes how failover-related connection options work with the driver. See "Connection Option Descriptions" for details about configuring the options. The step numbers in the table refer the procedure that follows the table

Table 3. Summary: Failover and Related Connection Options
Option	Characteristic
Alternate Servers (AlternateServers) (See step 1)	One or multiple alternate database servers. An IP address or server name identifying each server is required. Default: None
Connection Retry Count (ConnectionRetryCount) (See step 5)	Number of times the driver retries the primary database server, and if specified, alternate servers until a successful connection is established. Default: 0
Connection Retry Delay (ConnectionRetryDelay) (See step 6)	Wait interval, in seconds, between connection retry attempts when the Connection Retry Count option is set to a positive integer. Default: 3
Failover Granularity (FailoverGranularity) (See step 3)	Determines whether the driver fails the entire failover process or continues with the process if errors occur while trying to reestablish a lost connection. If set to 0 (Non-Atomic), the driver continues with the failover process and posts any errors on the statement on which they occur. If set to 1 (Atomic) the driver fails the entire failover process if an error is generated as the result of anything other than executing and repositioning a Select statement. If an error is generated as a result of repositioning a result set to the last row position, the driver continues with the failover process, but generates a warning that the Select statement must be reissued. If set to 2 (Atomic Including Repositioning), the driver fails the entire failover process if any error is generated as the result of restoring the state of the connection or the state of work in progress. If set to 3 (Disable Integrity Check), the driver does not verify that the rows that were restored during the failover process match the original rows. This value applies only when Failover Mode is set to 2 (Select). Default: 0 (Non-Atomic)
Failover Mode (FailoverMode) (See step 2)	Specifies the type of failover method the driver uses. If set to 0 (Connection), the driver provides failover protection for new connections only. If set to 1 (Extended Connection), the driver provides failover protection for new and lost connections, but not any work in progress. If set to 2 (Select), the driver provides failover protection for new and lost connections. In addition, it preserves the state of work performed by the last Select statement executed. Default: 0 (Connection)
Failover Preconnect (FailoverPreconnect) (See step 4)	Specifies whether the driver tries to connect to the primary and an alternate server at the same time. If set to 0 (Disabled), the driver tries to connect to an alternate server only when failover is caused by an unsuccessful connection attempt or a lost connection. This value provides the best performance, but your application typically experiences a short wait while the failover connection is attempted. If set to 1 (Enabled), the driver tries to connect to the primary and an alternate server at the same time. This can be useful if your application is time-sensitive and cannot absorb the wait for the failover connection to succeed. Default: 0 (Disabled)
Load Balancing (LoadBalancing) (See step 7)	Determines whether the driver uses client load balancing in its attempts to connect to the database servers (primary and alternate). You can specify one or multiple alternate servers by setting the Alternate Servers option. If set to 1 (Enabled), the driver uses client load balancing and attempts to connect to the database servers (primary and alternate servers) in random order. If set to 0 (Disabled), the driver does not use client load balancing and connects to each server based on their sequential order (primary server first, then, alternate servers in the order they are specified). Default: 0 (Disabled)

1. To configure connection failover, you must specify one or more alternate database servers that are tried at connection time if the primary server is not accepting connections. To do this, use the Alternate Servers connection option. Connection attempts continue until a connection is successfully established or until all the database servers in the list have been tried once (the default).

2. Choose a failover method by setting the Failover Mode connection option. The default method is Connection (FailoverMode=0).

3. If Failover Mode is Extended Connection (FailoverMode=1) or Select (FailoverMode=2), set the Failover Granularity connection option to specify how you want the driver to behave if errors occur while trying to reestablish a lost connection. The default behavior of the driver is Non-Atomic (FailoverGranularity=0), which continues with the failover process and posts any errors on the statement on which they occur. Other values are:

Atomic (FailoverGranularity=1): the driver fails the entire failover process if an error is generated as the result of anything other than executing and repositioning a Select statement. If an error is generated as a result of repositioning a result set to the last row position, the driver continues with the failover process, but generates a warning that the Select statement must be reissued.

Atomic including Repositioning (FailoverGranularity=2): the driver fails the entire failover process if any error is generated as the result of restoring the state of the connection or the state of work in progress.

Disable Integrity Check (FailoverGranularity=3): the driver does not verify that the rows restored during the failover process match the original rows. This value applies only when Failover Mode is set to Select (FailoverMode=2).

4. Optionally, enable the Failover Preconnect connection option (FailoverPreconnect=1) if you want the driver to establish a connection with the primary and an alternate server at the same time. This value applies only when Failover Mode is set to Extended Connection (FailoverMode=1) or Select (FailoverMode=2). 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=0).

5. Optionally, specify the number of times the driver attempts to connect to the primary and alternate database servers after the initial unsuccessful connection attempt. By default, the driver does not retry. To set this feature, use the Connection Retry Count connection option.

6. Optionally, specify the wait interval, in seconds, between attempts to connect to the primary and alternate database servers. The default interval is 3 seconds. To set this feature, use the Connection Retry Delay connection option.

7. Optionally, specify whether the driver will use client load balancing in its attempts to connect to primary and alternate database servers. If load balancing is enabled, the driver uses a random pattern instead of a sequential pattern in its attempts to connect. The default value is not to use load balancing. To set this feature, use the Load Balancing connection option.

In this section: