Client programs that have lost their connection to the Primary must be able to reconnect to the new Primary server (the old Secondary). You must code client applications to be able to:
1 Recognize that Primary is not available for write transactions any more.
2 Connect to the other server or switch to using previously created connection.
3 Take into account whether the current (interrupted) transaction was lost/aborted and must be re-executed on the new Primary server.
Getting the secondary server address
The easiest way to get the connection information for the Secondary database server is to use the ADMIN COMMAND 'hotstandby cominfo' command, which gives the connection information for the other server in the HSB pair.
About this task
Procedure
1 When your application first connects to Primary, the application can execute the ADMIN COMMAND 'hotstandby cominfo' command and store the result. Note that when the cominfo command returns a value, it does NOT imply that Primary and Secondary are currently connected. The “cominfo” command simply returns the value specified in the Connect parameter of the solid.ini configuration file, or the value most recently specified with the hsb parameter connect command. If you need to check the connect status between Primary and Secondary servers, you can use ADMIN COMMAND 'hotstandby status connect'.
2 Later, if Primary fails, the application can use the stored information to connect to Secondary (new Primary).
Detecting HotStandby server failure in client applications
To use the HotStandby (HSB) component, applications must know when to switch from the failed Primary to the Secondary (new Primary) server. There are a couple of possible ways to do this. The best way is to simply check the return codes from the functions that you call to see if you have received an error that indicates you should switch to the other server.
You may also monitor the states of the servers (for example, check the Primary server to see whether its state has changed to PRIMARY UNCERTAIN).
The errors that indicate you should try switching to another server include:
▪10013: Transaction is read only
▪10041: Database is read only
▪10047: Replication transaction aborted
▪11002: Disk full
▪11003: File write failed, configuration exceeded
▪14501: Operation failed
▪14502: Invalid rpc parameter
▪14503: Communication error
▪14506: Server is closed (for example, because it is currently the target of an HSB netcopy operation)
▪14510: Communication write operation failed
▪14511: Communication read operation failed
▪14518: Connection broken
▪14519: User thrown out (for example, because of some administrative operation)
▪14529: Operation timed out
▪20009: Session error, write operation failed
▪21306: Server not found, connect failed
▪21308: Connection is broken (write failed with code ...)
▪21318: Operation failed (unusual return code)
ODBC applications
The following error message is returned to ODBC applications that cannot establish a connection (for example, due to an inoperable database server):
▪SQLState = 08001 - Client unable to establish connection
In addition, the following solidDB® communication error message is produced:
▪21306 - Server 'server_name' not found, connection failed.
If a connection fails (for example, due to a network failure) in between operations, such as executing queries and fetching results, the following error message is returned:
▪SQLState = 08S01 - Communication link failure
JDBC applications
The following error message is returned to JDBC applications that cannot establish a connection (for example, due to an inoperable database):
▪SQLState = 08001 - Unable to connect to data source.
If a connection fails (for example, due to a network failure) in between operations, such as executing queries and fetching results, the following error message is returned:
▪SQLState = 08S01 - Communication link failure
Note ODBC and JDBC use different error messages for the same error code (08001).
Switching the application to the new primary
After the application detects that it cannot send transactions to the “old Primary” server, the application must poll the old Primary and old Secondary servers until it finds a server that is in PRIMARY ACTIVE, PRIMARY ALONE, or STANDALONE state.
Polling is accomplished by having the application attempt to connect to the servers and check the status of the servers when the connection is established. When the connect is successful, the client can request the server state by using SQL function HOTSTANDBY_STATE, which is described in section Using the HOTSTANDBY_STATE function.
CAUTION: After the switch, all open database objects, such as prepared statements, open cursors and transactions, are no longer active. Thus, you must initialize these objects again. Also, if you were using Temporary Tables or Transient Tables (solidDB® main memory engine features), the tables will be empty on the new Primary.
Using the HOTSTANDBY_CONNECTSTATUS function
To verify connect status information when reconnecting to a Primary server from an application, you can use the HOTSTANDBY_CONNECTSTATUS function. This function is equivalent to the administrative command hotstandby status connect.
The function has no arguments and returns one of the following status values:
Status
Description
CONNECTED
The connection is active. This status is returned from both the Primary and Secondary servers.
CONNECTING
The Primary server is connecting to the Secondary server. This status is returned from both the Primary and Secondary servers.
CATCHUP
The Primary server is connected to the Secondary server, but the transaction log is not yet fully copied. This status is returned from both the Primary and Secondary server.
BROKEN
The connection is broken. This status is returned from both the Primary and Secondary servers.
Using the HOTSTANDBY_STATE function
To implement application polling of the Primary and Secondary servers, you can use the HOTSTANDBY_STATE function. This function is equivalent to the administrative command hotstandbystate. It allows the application request the current HotStandby state when it is connected to the server.
Note This function has no arguments. For a description of each possible state that this function may return, see Verifying HotStandby server states.
Sample pseudo-code
An application, whether or not it is HSB-enabled, should have error handling that allows the application to replay a failed/aborted transaction.
In a non-HSB environment, a transaction may be aborted because of a concurrency conflict (optimistic tables) or deadlock (pessimistic tables). The application must catch these error situations and either automatically retry the transaction or ask interactive user to re-execute the transaction.
If your application already has code to handle failed or aborted transactions, then it is relatively easy to extend this code to make use of HSB.
In a very simplified example, the application pseudo-code with proper error handling for a non-HA-aware application handling looks something like this:
BEGIN TRANSACTION EXECUTE APPLICATION LOGIC PREPARE & EXECUTE STATEMENTS COMMIT TRANSACTION IF ERROR OCCURRED IF ERROR == concurrency conflict or deadlock GO TO BEGIN TRANSACTION END IF other error handling END IF ;
Improving the above application to make it HA-aware is very simple. You must add code so that the application can:
▪Connect to either of the two servers instead of only one; and
▪In the case of an error, find the server that is currently in one of the following states: PRIMARY ACTIVE, PRIMARY ALONE or STANDALONE.
The pseudo-code should look similar to the following:
BEGIN TRANSACTION EXECUTE APPLICATION LOGIC PREPARE & EXECUTE STATEMENTS COMMIT TRANSACTION IF ERROR OCCURRED IF ERROR == server unavailable for write transactions FIND CURRENT PRIMARY SERVER GO TO BEGIN TRANSACTION END IF IF ERROR == concurrency conflict or deadlock GO TO BEGIN TRANSACTION END IF IF ERROR == something else other error handling END IF END IF
The logic to find the current primary server is also very simple. Just check the current state of both servers (try to reconnect if necessary) and if either of them is PRIMARY ACTIVE, PRIMARY ALONE or STANDALONE, set that server as the current primary. If neither server meets that criterion, wait awhile and retry checking the current server states.