This sample C application demonstrates the functionality of transparent failover in HotStandby (HSB) configurations.
The files for the sample are located in the soliddb-installdir\samples\tf directory. For general information about running the samples, see Samples.
Transparent Failover is a feature of Transparent Connectivity (TC); a method of handling the logical TC connection when working with HSB servers by making a server switch as transparent as possible, so the application can treat the HSB pair of servers as a single server, see Failure transparency in Transparent Connectivity.
solidDB provides the following levels of failover transparency:
▪ CONNECTION: the driver is reconnected automatically to a new primary server but the application must rebuild the session state, including prepared statements.
▪ SESSION: same as CONNECTION, but most of the session state is preserved, including prepared statements.
This sample is built for the CONNECTION level of failover transparency.
If the physical connection fails or there is a switch of status in the pair of HSB servers, a rollback is required.
When an application receives the error 25216 Connection switch, some session context might be lost, the following issues must be handled:
▪ uncommitted writes must be re-executed after a forced rollback,
▪ reads might not complete,
▪ commits might not succeed,
▪ prepared statements must be prepared again (although statement handles stay allocated),
▪ session settings must be recreated (so SET statements must be re-executed).
The sample application (tf1.c) completes the following actions:
▪ Connect to database by using a transparent connection that specifies Transparent Failover.
▪ Execute a number of INSERT and SELECT statements.
▪ Rebuild required settings and re-execute INSERT statements that were interrupted when a primary server switch occurred.
Note The sample application assumes that the HSB servers are using ports 2315 and 2325, but you can provide a TF connect string as a command line argument if your servers have different ports (see the application source for more information).
Running the sample
Run the runme script (runme.bat in Windows) to demonstrate how an application can handle the issues that are associated with the switch of status between a pair of HSB servers:
Note that the runme script also uses files from the samples\hsb folder.
The runme script completes the following actions:
1 Compile the application.
2 Start two servers with default parameters (the servers are configured as HSB servers in solid.ini so both servers start in SECONDARY_ALONE state).
3 Configure HSB so that one server is the primary server and the other is the secondary server, and verify that the servers have the expected states.
4 Run the application (which loops through four iterations of selecting and inserting data).
5 While the application is running, switch the primary server to the secondary server, in order to demonstrate transparent failover.
Note You might need to adjust the number of iterations (value of nloops variable in tf1.c) or the amount of time the script waits before switching the status of the HSB servers (see interrupt: section in makefile), in order for the application to catch the exception.