The Teradata JDBC Driver Engineering team receives a lot of questions about what happens when a JDBC connection is created. Let’s clarify the concepts Laddered Concurrent Connect (LCC) versus COP Discovery versus logon, and review what the Teradata JDBC Driver does to create a JDBC connection.
First, some definitions…
“COP” stands for Communications Processor, and is a term originating from Teradata’s earliest database appliances in the 1980s. In modern usage, a “COP” is a Teradata Database node that is running a Teradata Database Gateway process.
“COP Discovery” refers to the process of performing multiple DNS lookups to identify all the Teradata Database nodes that the client software could potentially connect to.
“Laddered Concurrent Connect” (LCC) refers to a feature in Teradata client interface software products in which the client software attempts to connect to multiple Teradata Database nodes in parallel, rather than sequentially. You can read more about LCC in this article: https://downloads.teradata.com/connectivity/articles/laddered-concurrent-connect-lcc-client-performance-improvements
It’s important to understand that COP Discovery is completely separate from LCC, and both are completely separate from logon.
A command-line Java application will typically obtain a JDBC connection from the JDBC DriverManager with code similar to the following.
Connection con = DriverManager.getConnection(“jdbc:teradata://hostname/TMODE=ANSI,CHARSET=UTF8”, username, password);
A Java application running in an application server will typically obtain a JDBC connection from a connection pool manager. If the connection pool doesn’t already contain a suitable connection, then a new JDBC connection must be created for the application.
In either scenario, the Teradata JDBC Driver must perform a series of steps to create the JDBC connection. The steps are described below.
The Teradata JDBC Driver performs COP Discovery first, and produces a two-dimensional array of COP hostnames and their IP addresses.
COP Discovery is the process of taking a hostname (really a hostname prefix) and then appending “cop” and a number to the end of the hostname prefix, and verifying whether a DNS lookup indicates that the resulting hostname is defined. The process stops when a DNS lookup failure is encountered. Given a hostname prefix of “teradata”, DNS lookups would be attempted with the following pattern.
teradatacop1 teradatacop2 teradatacop3
If a domain suffix is specified for the hostname prefix, then the “cop” and number suffix are applied to the hostname. Given a hostname prefix of “teradata.domain.com”, DNS lookups would be attempted with the following pattern.
teradatacop1.domain.com teradatacop2.domain.com teradatacop3.domain.com
The Teradata JDBC Driver’s default behavior is to perform COP Discovery. To turn off COP Discovery, you must specify the COP=OFF connection parameter. The relevant documentation is located here: https://downloads.teradata.com/doc/connectivity/jdbc/reference/current/jdbcug_chapter_2.html#URL_COP
Some other Teradata client interface products permit a maximum number of COPs to be specified, in order to set an upper bound on the number of DNS lookups. The Teradata JDBC Driver does not offer a feature like that. You cannot specify a COP count for the Teradata JDBC Driver’s COP connection parameter.
Instead, Teradata JDBC Driver 16.00.00.28 introduced a COPLAST=ON connection parmeter. When COPLAST=ON is specified, and COP Discovery is enabled, then the Teradata JDBC Driver will first perform a DNS lookup for a coplast hostname to obtain the IP address of the last COP hostname before performing COP Discovery. Subsequently, during COP Discovery, the Teradata JDBC Driver will stop searching for COP hostnames when either an unknown COP hostname is encountered, or a COP hostname is encountered whose IP address matches the IP address of the coplast hostname. The relevant documentation is located here: https://downloads.teradata.com/doc/connectivity/jdbc/reference/current/jdbcug_chapter_2.html#URL_COPLAST
Each COP hostname can have one or more IP addresses associated with it. The Teradata JDBC Driver’s COP Discovery obtains all the IP addresses for all the COP hostnames.
The Teradata JDBC Driver creates a two-dimensional array to hold all the IP addresses for all the COP hostnames. Any duplicate IP addresses are omitted from the two-dimensional array.
COP Discovery is single-threaded and occurs sequentially.
If COP Discovery fails to discover any cop-suffixed hostnames, or if COP Discovery is turned off with the COP=OFF connection parameter, then the Teradata JDBC Driver performs one DNS lookup for the specified hostname, and obtains all the IP addresses associated with that hostname.
If a literal IP address was specified as the hostname, then the Teradata JDBC Driver doesn’t perform COP Discovery, and simply uses the specified IP address.
Laddered Concurrent Connect (LCC) occurs second, and uses the two-dimensional array as the list of possible IP addresses to choose from. Because duplicate IP addresses are omitted by COP Discovery, the Teradata JDBC Driver will only attempt to connect to each IP address once at most.
The purpose of LCC is to make multiple TCP socket connect attempts in parallel.
The Teradata JDBC Driver’s LCC is multi-threaded, and uses a blocking socket connect method. In contrast, other Teradata client interface products’ LCC implementations use a single thread and asynchronous TCP socket operations.
When the Teradata JDBC Driver finally makes a successful TCP socket connection, any other TCP socket connection attempts in progress are terminated with a TCP socket close.
When a successful TCP socket connection is made, the Teradata JDBC Driver remembers:
- the original hostname (without COP suffix),
- the COP hostname that was chosen for the session,
- and the IP address that was chosen (there could have been several IP addresses for that COP hostname).
Logon is the third step — using the first successfully-connected TCP socket.
It is never the case that multiple logon attempts occur in parallel. Logon is single-threaded.
The credentials (username and password) are always encrypted before they are transmitted to the Teradata Database, regardless of the setting of the ENCRYPTDATA connection parameter. The ENCRYPTDATA connection parameter does not control the encryption of credentials; instead, it controls whether encryption is provided for data transmitted to and from the Teradata Database after logon.
After a successful logon, the fourth step is to modify an expired password, if needed. An expired password will be automatically set to a new password if the user’s password has expired, and a new password was specified with the NEW_PASSWORD connection parameter.
The relevant documentation is located here: https://downloads.teradata.com/doc/connectivity/jdbc/reference/current/jdbcug_chapter_2.html#URL_NEW_PASSWORD
If the logged-on user has a startup string, and the RUNSTARTUP=ON connection parameter was specified, then the Teradata JDBC Driver will execute the user’s startup string.
The relevant documentation is located here:
If the DATABASE connection parameter was specified, then the current database will be switched to the specified database.
The relevant documentation is located here: https://downloads.teradata.com/doc/connectivity/jdbc/reference/current/jdbcug_chapter_2.html#URL_DATABASE
The new JDBC connection is returned to the application.