JDBC new Interface for Parallel Connections

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

Introduction

The existing interface for establishing parallel connections to the Exasol Database required users to create a main connection and then call the EnterParallel 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.

Steps for Old Interface

1. Establish a main connection.
2. Call the method EnterParallel with the desired number of parallel connections. The database will open ports on the DB for parallel connections and return the number of parallel connections that need to be established, along with the IP and port required to establish an parallel connections. And the function will return the number of parallel connections that need to be established.
3. Get the worker token by invoking the method GetWorkerToken.
4. Get the list of IP addresses and ports by invoking the method GetWorkerHosts. This will return a list of strings, each row containing the IP and port required to establish a parallel connection.
5. To establish a parallel connection, use one of the provided IP and port combinations, along with the token and worker parameter on the connection string.

Disadvantages of the Old Interface

The old interface for parallel connections had limitations that required a special configuration to calculate the IP address of the host, which was inconvenient. Additionally, it opened a port in the range of 20000-21000 to establish a worker connection, which was restrictive. However, these limitations have been eliminated in the new interface, providing a more seamless and flexible experience for users.

New Interface

The new interface has several advantages over the old one. Firstly, it allows the user to specify the hosts that should be used for parallel connections. Secondly, it eliminates the need for the database to calculate the IP address and port. Instead, the driver resolves the DNS entry if available in the connection string. Thirdly, it introduces a new session ID attribute for the connection string.

Steps for New Interface

The new workflow for establishing parallel connections is as follows:

1. Establish a main connection.
2. Call RequestParallelConnections with the desired number of parallel connections. The function will return the number of parallel connections that need to be established. The IP address and port are parsed from the connection string provided in the main connection.
3. Get the worker token by invoking the method GetWorkerToken.
4. Get the list of IP address and port by invoking the method GetAvailableWorkerHosts.
5. Get the session ID of the main connection using the method getSessionID.
6. To establish the parallel connection, use one of the IP and port combinations provided, along with the token, session ID, and worker parameter on the connection string.

Advantages of the New Interface

The new interface for parallel connections overcomes the challenges associated with the old one. Firstly, it allows users to specify the hosts that should be used for parallel connections, leading to optimal performance. Secondly, it eliminates the need for the database to calculate the IP address and port, making it feasible to use cloud databases. Thirdly, it introduces a new session ID attribute for the connection string that simplifies the workflow for establishing parallel connections.

Compatibility

The older interface for parallel connections is marked as deprecated and will be removed in later releases. The new interface and the old one will be supported simultaneously by JDBC if the database supports it. However, if the new interface is used with old databases, an error message will be displayed that states "Request Parallel Connections is not supported. Please use EnterParallel." To check whether the database supports the new interface, the attribute isRequestParallelConnectionsSupported can be called after establishing the main connection. It will return true if the database supports the new interface, else it returns false.

Error Messages and Scenarios for JDBC Parallel Connections

1. "Insufficient Hosts are provided. Required Hosts: 10, Provided Hosts: 5": This error message is displayed in the new interface when the number of available hosts provided in the connection string is less than the required number of parallel connections. This error can be seen when the user has specified a lower number of hosts than the number of parallel connections needed.
2. "Request Parallel Connections is not supported. Please use EnterParallel.": This error message is displayed in the new interface when the database does not support the new interface for parallel connections. This error can be seen when the user tries to use the new interface with an older database that does not support it.

JDBC Connection String Attributes for Parallel Connections

JDBC Connection String is a standard way of specifying the properties needed to connect to a database. For parallel connections, the connection string includes several attributes that are used to establish a successful parallel connection.

1. worker: This attribute specifies the worker ID for the parallel connection. In both the old and new interfaces, the worker is required to establish a parallel connection.
2. workertoken: This attribute specifies the worker token for the parallel connection. In both the old and new interfaces, the workertoken is required to establish a parallel connection.
3. sessionid: This attribute is introduced in the new interface and specifies the session ID for the main connection. The session ID is used to establish the parallel connection.

DB Supported

This feature is supported from Exasol DB 8.32+.

Changed behavior