Properties for connecting to high-availability cluster servers through HCL OneDB Connection Managers

A JDBC application can connect to Connection Manager, just as the application might connect to a database server. Application connection requests are then redirected to the most appropriate server in a high-availability cluster.

You can configure multiple Connection Managers, and then create a Connection Manager group entry in sqlhost file that is used by the Java™ application server. If one Connection Manager fails, connection requests can be directed to working Connection Managers. The SQLH_FILE connection property directs the JDBC driver to search for group entries.

To connect to the HCL OneDB™ Connection Manager that then connects to the servers of a high-availability cluster, you must include the following properties in the connection URL or DataSource:
ONEDB_SERVER=CM_or_group_name
SQLH_TYPE=FILE
SQLH_FILE=sqlhosts
USER=user_name
PASSWORD=password
Include the following properties in the connection URL to prevent your Java applications from waiting indefinitely if a Connection Manager is running, but has a hung connection.
CONNECT_RETRIES=value
CONNECT_TIMEOUT=value
LOGINTIMEOUT=value
The values are set based on the network environment.

Example 1: Connecting to a high-availability cluster through the HCL OneDB Connection Manager

In this example, you have the following system setup:
  • You have a high-availability cluster (my_cluster) that is composed of four servers.
  • The user name on all cluster servers is my_user.
  • The password on all cluster servers is my_password.
  • connection_manager, on cmhost1.example.com uses the following configuration file:
    NAME connection_manager

CLUSTER my_cluster
{
   ONEDB_SERVER my_servers
   SLA sla_primary     DBSERVERS=PRI
   SLA sla_secondaries DBSERVERS=SDS,HDR,RSS
   FOC ORDER=ENABLED \
       PRIORITY=1
}
  • You have a Java application server on host1.example.com, and the Java application server uses the following sqlhost file entries:
    #dbservername       nettype    hostname             servicename  options
 sla_primary      onsoctcp   cmhost1.example.com  cm_port_1
 sla_secondaries  onsoctcp   cmhost1.example.com  cm_port_1
  • If the initial connection attempt by the client fails, you want it to retry two times.
  • You want the CONNECT statement to wait 10 seconds to establish a connection.
  • You want the connection to fail if the server port is polled and does not connect within 10 milliseconds.
To connect the Java application client to the primary server of my_cluster, use the following URL:
jdbc:onedb://ONEDB_SERVER=sla_primary;
   SQLH_TYPE=FILE;SQLH_FILE=sqlhosts;
   USER=my_user_name;PASSWORD=my_password;
   CONNECT_RETRIES=2;CONNECT_TIMEOUT=10;LOGINTIMEOUT=10
To connect the Java application client to a secondary server of my_cluster, use the following URL:
jdbc:onedb://ONEDB_SERVER=sla_secondaries;
   SQLH_TYPE=FILE;SQLH_FILE=sqlhosts;
   USER=my_user_name;PASSWORD=my_password;
   CONNECT_RETRIES=2;CONNECT_TIMEOUT=10;LOGINTIMEOUT=10

Example 2: Connecting to a high-availability cluster through HCL OneDB Connection Managers

In this example, you have the following system setup:
  • You have a high-availability cluster (my_cluster) that is composed of four servers.
  • The user name on all cluster servers is my_user.
  • The password on all cluster servers is my_password.
  • connection_manager_1, on cmhost1.example.com uses the following configuration file for client redirection and failover:
    NAME connection_manager_1

CLUSTER my_cluster
{
   ONEDB_SERVER my_servers
   SLA sla_primary_1 DBSERVERS=PRI
   FOC ORDER=ENABLED \
       PRIORITY=1
   CMALARMPROGRAM $ONEDB_HOME/etc/CMALARMPROGRAM.sh
}
  • connection_manager_2, on cmhost2.example.com uses the following configuration file for client redirection and failover:
    NAME connection_manager_2

CLUSTER my_cluster
{
   ONEDB_SERVER my_servers
   SLA sla_primary_1 DBSERVERS=PRI
   FOC ORDER=ENABLED \
       PRIORITY=2
   CMALARMPROGRAM $ONEDB_HOME/etc/CMALARMPROGRAM.sh
}
  • You have a Java application server on host1.example.com, and the Java application server uses the following sqlhost file entries:
    #dbservername       nettype    hostname             servicename  options
 g_primary          group      -                    -            c=1,e=sla_primary_2
 sla_primary_1      onsoctcp   cmhost1.example.com  cm_port_1    g=g_primary
 sla_primary_2      onsoctcp   cmhost2.example.com  cm_port_2    g=g_primary
  • If the initial connection attempt by the client fails, you want it to retry two times.
  • You want the CONNECT statement to wait 10 seconds to establish a connection.
  • You want the connection to fail if the server port is polled and does not connect within 10 milliseconds.
To connect the Java application client to the primary server of my_cluster through either connection_manager_1 or connection_manager_2, use the following URL:
jdbc:onedb://ONEDB_SERVER=g_primary;
   SQLH_TYPE=FILE;SQLH_FILE=sqlhosts;
   USER=my_user_name;PASSWORD=my_password;
   CONNECT_RETRIES=2;CONNECT_TIMEOUT=10;LOGINTIMEOUT=10