CLI New Interface for parallel connections

Detail name	Value
Changelog Number	21242
Type	Improvement
Status	Resolved
Fix Versions	ODBC 24.2.0
Resolution Date	2024-11-11

Description

Call Level Interface SDK is a native C++ interface to access Exasol database (see more in Call Level Interface SDK).

The existing interface for establishing parallel connections to the Exasol Database required users to create a main connection and then call the EXAEnterParallel function to open ports for the required parallel connections. The IP address and port were determined by the DB, leading to complications when dealing with Cloud platforms like AWS, Azure, and GCP as well as on-prem clusters. In those cases, an special IP configuration is required. To address these issues, a new interface has been introduced that gives users greater control over the IP address and port for parallel connections.

Old Interface for Parallel Connections

1. Create a main connection using the EXAServerConnect.
2. After the main connection is established, call the EXAEnterParallel function with the number of desired parallel connections to open ports on the DB for parallel connections. The function will return the number of parallel connections that need to be established, parallel token, as well as connection struct (ConnectionStru) containing information about the IP and Port to establish the parallel connection.
3. Create an SQL HDBC and HENV Handle.
4. Use the above information to start the parallel connection using EXAWorkerConnect.

New Interface for Parallel Connections

1. Create a main connection using the EXAServerConnect.
2. After the main connection is established, call the EXARequestParallelConnections function with the number of desired parallel connections.
   The EXARequestParallelConnections function takes in the number of parallel connections as an argument. The function then returns the number of parallel connections that need to be established, parallel token to establish parallel connection, and the connection struct (ConnectionHostsStruct), which contains the IP address and port to establish the parallel connection.
   The IP address and port in the ConnectionHostsStruct are parsed from the connection string provided in the main connection. This means that if the connection string contains a DNS entry, the CLI will resolve it, and the IP address and port will be selected accordingly. And the hosts will be shuffled. Additionally, if the number of hosts (after resolving DNS entries) is less than the number of parallel connections requested by the user, an error message will be thrown, indicating that insufficient hosts were provided.
   In addition to the IP address and port, the ConnectionHostsStruct also includes the SSLCertificate, AuthMethod, HostTimeout, LoginTimeout, Encryption, LogMode, EXALogFile, and Fingerprint parameters. These parameters are obtained from the main connection and will be used for the parallel connections.
3. Create an SQL HDBC and HENV Handle.
4. Set the connection attribute to the handle. Set EXA_ATTR_WORKER to "Y" and EXA_ATTR_CONNECTIONHOSTSSTRUCT_PTR to the ConnectionHostsStruct object pointer.
5. Call EXAServerConnect with an empty/null host and port (User name and password are mandatory). This will start the parallel connections.

The new interface allows users to request parallel connections from the main connection itself and provides greater control over the IP and port for parallel connections.

Advantages

Enhanced Control: With the new interface, users have control over the IP address and port for establishing parallel connections. The IP address and port are parsed from the connection string provided in the main connection. This allows users to choose the hosts to be used for parallel connections and eliminates the need for the DB to determine the IP address.

OpenID Authentication: The new interface supports OpenID Authentication for parallel connections.

Better Error Handling: In case the connection string provided by the user contains an insufficient number of hosts, an error will be thrown. The new interface also supports better error handling for cases where the Connection Hosts Struct Pointer is not provided.

Elimination of Port Range for Parallel Connections: The requirement to use ports 20000-21000 for parallel connections has been removed. Instead, the database port will now handle parallel connections.

Interface Update

Deprecation: The older implementation has been marked as deprecated and will be removed in the later releases. Users will need to upgrade to the latest interface.

Compatibility: If the new interface is used with an older DB that does not support it, an error will be experienced. To identify if the DB supports the new interface, users can use the attribute "EXA_REQUEST_PARALLEL_CONNECTIONS_SUPPORTED" after establishing the main connection.

Overall, the new interface for parallel connections is an improvement over the older implementation. It provides greater control, better error-handling and support for OpenID authentication. However, users will need to be aware of the compatibility issues with older DBs and invest some time in understanding the new interface.

DB Supported

This feature is supported from Exasol DB 8.32+.

Error Messages

Error messages and the scenarios where they can be seen for the new interface:

1. Error Message: "Insufficient Hosts are provided. Required Hosts: 10, Provided Hosts: 5." Scenario: When the number of hosts in the connection string provided by the user is less than the number of parallel connections requested by the user, an error message will be thrown.
2. Error Message: "Connection Host Struct Pointer is not provided." Scenario: When the Connection Host Struct Pointer is not set in the handle, an error message will be thrown when calling EXAServerConnect.
3. Error Message: "Request Parallel Connections is not supported. Please use Enter Parallel." Scenario: When a user tries to use the new interface for a database that does not support it, an error message will be thrown. This can be checked using the "EXA_REQUEST_PARALLEL_CONNECTIONS_SUPPORTED" attribute after establishing the main connection.

Changed behavior