teradatasql
Version:
Teradata SQL Driver for Node.js
343 lines (263 loc) • 161 kB
Markdown
## Teradata SQL Driver for Node.js
This package enables Node.js applications to connect to the Teradata Database.
This package requires 64-bit Node.js v18.20.7 or later and runs on the following operating systems and processor architectures. 32-bit Node.js is not supported.
* Windows x64 on 64-bit Intel and AMD processors
* macOS on 64-bit ARM processors
* macOS on 64-bit Intel processors
* Linux x64 on 64-bit Intel and AMD processors
* Linux ARM64 on 64-bit ARM processors
For community support, please visit [Teradata Community](https://support.teradata.com/community).
For Teradata customer support, please visit [Teradata Customer Service](https://support.teradata.com/).
Please note, this driver may contain beta/preview features ("Beta Features"). As such, by downloading and/or using the driver, in addition to agreeing to the licensing terms below, you acknowledge that the Beta Features are experimental in nature and that the Beta Features are provided "AS IS" and may not be functional on any machine or in any environment.
Copyright 2025 Teradata. All Rights Reserved.
### Table of Contents
* [Features](#Features)
* [Limitations](#Limitations)
* [Installation](#Installation)
* [License](#License)
* [Documentation](#Documentation)
* [Sample Programs](#SamplePrograms)
* [Using the Driver](#Using)
* [Connection Parameters](#ConnectionParameters)
* [COP Discovery](#COPDiscovery)
* [Stored Password Protection](#StoredPasswordProtection)
* [Logon Authentication Methods](#LogonMethods)
* [Client Attributes](#ClientAttributes)
* [User STARTUP SQL Request](#UserStartup)
* [Transaction Mode](#TransactionMode)
* [Auto-Commit](#AutoCommit)
* [Data Types](#DataTypes)
* [Null Values](#NullValues)
* [Undefined Values](#UndefinedValues)
* [Character Export Width](#CharacterExportWidth)
* [Module Constructors](#ModuleConstructors)
* [Module Exceptions](#ModuleExceptions)
* [Connection Attributes](#ConnectionAttributes)
* [Connection Methods](#ConnectionMethods)
* [Cursor Attributes](#CursorAttributes)
* [Cursor Methods](#CursorMethods)
* [Type Objects](#TypeObjects)
* [Escape Syntax](#EscapeSyntax)
* [FastLoad](#FastLoad)
* [FastExport](#FastExport)
* [CSV Batch Inserts](#CSVBatchInserts)
* [CSV Export Results](#CSVExportResults)
* [Command Line Interface](#CommandLineInterface)
* [Change Log](#ChangeLog)
<a id="Features"></a>
### Features
At the present time, the driver offers the following features.
* Supported for use with Teradata database 16.20 and later releases.
* [COP Discovery](#COPDiscovery).
* Laddered Concurrent Connect.
* [HTTPS](https://en.wikipedia.org/wiki/HTTPS)/[TLS](https://en.wikipedia.org/wiki/Transport_Layer_Security) connections with Teradata database 16.20.53.30 and later.
* Encrypted logon.
* [GSS-API](https://en.wikipedia.org/wiki/Generic_Security_Services_Application_Program_Interface) logon authentication methods `KRB5` (Kerberos), `LDAP`, `TD2`, and `TDNEGO`.
* [OpenID Connect (OIDC)](https://en.wikipedia.org/wiki/OpenID#OpenID_Connect_(OIDC)) logon authentication methods `BEARER`, `BROWSER`, `CODE`, `CRED`, `JWT`, `ROPC`, and `SECRET`.
* Data encryption provided by TLS for HTTPS connections.
* For non-HTTPS connections, data encryption governed by central administration or enabled via the `encryptdata` connection parameter.
* Unicode character data transferred via the UTF8 session character set.
* [Auto-commit]((#AutoCommit)) for ANSI and TERA transaction modes.
* Result set row size up to 1 MB.
* Multi-statement requests that return multiple result sets.
* Most JDBC escape syntax.
* Parameterized SQL requests with question-mark parameter markers.
* Parameterized batch SQL requests with multiple rows of data bound to question-mark parameter markers.
* Auto-Generated Key Retrieval (AGKR) for identity column values and more.
* Large Object (LOB) support for the BLOB and CLOB data types.
* Complex data types such as `XML`, `JSON`, `DATASET STORAGE FORMAT AVRO`, and `DATASET STORAGE FORMAT CSV`.
* ElicitFile protocol support for DDL commands that create external UDFs or stored procedures and upload a file from client to database.
* `CREATE PROCEDURE` and `REPLACE PROCEDURE` commands.
* Stored Procedure Dynamic Result Sets.
* FastLoad and FastExport.
* Monitor partition.
<a id="Limitations"></a>
### Limitations
* The UTF8 session character set is always used. The `charset` connection parameter is not supported.
* No support yet for Recoverable Network Protocol and Redrive.
<a id="Installation"></a>
### Installation
The driver depends on the `ffi-napi`, `ref-napi`, `ref-array-di` packages which are available from [npmjs.com](http://www.npmjs.com).
Use `npm install teradatasql` to download and install the driver and its dependencies automatically.
<a id="License"></a>
### License
Use of the driver is governed by the [License Agreement for the Teradata SQL Driver for Node.js](https://github.com/Teradata/nodejs-driver/blob/develop/LICENSE).
When the driver is installed, the `LICENSE` and `THIRDPARTYLICENSE` files are placed in the `teradatasql` directory under your `node_modules` installation directory.
In addition to the license terms, the driver may contain beta/preview features ("Beta Features"). As such, by downloading and/or using the driver, in addition to the licensing terms, you acknowledge that the Beta Features are experimental in nature and that the Beta Features are provided "AS IS" and may not be functional on any machine or in any environment.
<a id="Documentation"></a>
### Documentation
When the driver is installed, the `README.md` file is placed in the `teradatasql` directory under your `node_modules` installation directory. This permits you to view the documentation offline, when you are not connected to the Internet.
The `README.md` file is a plain text file containing the documentation for the driver. While the file can be viewed with any text file viewer or editor, your viewing experience will be best with an editor that understands Markdown format.
<a id="SamplePrograms"></a>
### Sample Programs
Sample programs are provided to demonstrate how to use the driver. When the driver is installed, the sample programs are placed in the `teradatasql/samples` directory under your `node_modules` installation directory.
The sample programs are coded with a fake database hostname `whomooz`, username `guest`, and password `please`. Substitute your actual database hostname and credentials before running a sample program.
Program | Purpose
-------------------------------------------------------------------------------------------------------------------- | ---
[AGKRBatchInsert.ts](https://github.com/Teradata/nodejs-driver/blob/develop/samples/AGKRBatchInsert.ts) | Demonstrates how to insert a batch of rows with Auto-Generated Key Retrieval (AGKR)
[AGKRInsertSelect.ts](https://github.com/Teradata/nodejs-driver/blob/develop/samples/AGKRInsertSelect.ts) | Demonstrates Insert/Select with Auto-Generated Key Retrieval (AGKR)
[BatchInsert.ts](https://github.com/Teradata/nodejs-driver/blob/develop/samples/BatchInsert.ts) | Demonstrates how to insert a batch of rows
[BatchInsertCSV.ts](https://github.com/Teradata/nodejs-driver/blob/develop/samples/BatchInsertCSV.ts) | Demonstrates how to insert a batch of rows from a CSV file
[BatchInsPerf.ts](https://github.com/Teradata/nodejs-driver/blob/develop/samples/BatchInsPerf.ts) | Measures time to insert one million rows
[CancelSleep.ts](https://github.com/Teradata/nodejs-driver/blob/develop/samples/CancelSleep.ts) | Demonstrates how to use the cancel method to interrupt a query
[CharPadding.ts](https://github.com/Teradata/nodejs-driver/blob/develop/samples/CharPadding.ts) | Demonstrates the database's *Character Export Width* behavior
[CommitRollback.ts](https://github.com/Teradata/nodejs-driver/blob/develop/samples/CommitRollback.ts) | Demonstrates commit and rollback methods with auto-commit off.
[DecimalDigits.ts](https://github.com/Teradata/nodejs-driver/blob/develop/samples/DecimalDigits.ts) | Demonstrates how to format decimal.Decimal values.
[DriverDatabaseVersion.ts](https://github.com/Teradata/nodejs-driver/blob/develop/samples/DriverDatabaseVersion.ts) | Displays the driver version and database version
[ElicitFile.ts](https://github.com/Teradata/nodejs-driver/blob/develop/samples/ElicitFile.ts) | Demonstrates C source file upload to create a User-Defined Function (UDF)
[ExecuteRequest.ts](https://github.com/Teradata/nodejs-driver/blob/develop/samples/ExecuteRequest.ts) | Demonstrates how to execute a SQL request and display results
[ExportCSVResult.ts](https://github.com/Teradata/nodejs-driver/blob/develop/samples/ExportCSVResult.ts) | Demonstrates how to export a query result set to a CSV file
[ExportCSVResults.ts](https://github.com/Teradata/nodejs-driver/blob/develop/samples/ExportCSVResults.ts) | Demonstrates how to export multiple query result sets to CSV files
[FakeExportCSVResults.ts](https://github.com/Teradata/nodejs-driver/blob/develop/samples/FakeExportCSVResults.ts) | Demonstrates how to export multiple query result sets with the metadata to CSV files
[FakeResultSetCon.ts](https://github.com/Teradata/nodejs-driver/blob/develop/samples/FakeResultSetCon.ts) | Demonstrates connection parameter for fake result sets
[FakeResultSetEsc.ts](https://github.com/Teradata/nodejs-driver/blob/develop/samples/FakeResultSetEsc.ts) | Demonstrates escape function for fake result sets
[FastExportCSV.ts](https://github.com/Teradata/nodejs-driver/blob/develop/samples/FastExportCSV.ts) | Demonstrates how to FastExport rows from a table to a CSV file
[FastExportTable.ts](https://github.com/Teradata/nodejs-driver/blob/develop/samples/FastExportTable.ts) | Demonstrates how to FastExport rows from a table
[FastLoadBatch.ts](https://github.com/Teradata/nodejs-driver/blob/develop/samples/FastLoadBatch.ts) | Demonstrates how to FastLoad batches of rows
[FastLoadCSV.ts](https://github.com/Teradata/nodejs-driver/blob/develop/samples/FastLoadCSV.ts) | Demonstrates how to FastLoad batches of rows from a CSV file
[HelpSession.ts](https://github.com/Teradata/nodejs-driver/blob/develop/samples/HelpSession.ts) | Displays session information
[IgnoreErrors.ts](https://github.com/Teradata/nodejs-driver/blob/develop/samples/IgnoreErrors.ts) | Demonstrates how to ignore errors
[InsertLob.ts](https://github.com/Teradata/nodejs-driver/blob/develop/samples/InsertLob.ts) | Demonstrates how to insert BLOB and CLOB values
[InsertXML.ts](https://github.com/Teradata/nodejs-driver/blob/develop/samples/InsertXML.ts) | Demonstrates how to insert and retrieve XML values
[LoadCSVFile.ts](https://github.com/Teradata/nodejs-driver/blob/develop/samples/LoadCSVFile.ts) | Demonstrates how to load data from a CSV file into a table
[LobLocators.ts](https://github.com/Teradata/nodejs-driver/blob/develop/samples/LobLocators.ts) | Demonstrates how to use LOB locators
[MetadataFromPrepare.ts](https://github.com/Teradata/nodejs-driver/blob/develop/samples/MetadataFromPrepare.ts) | Demonstrates how to prepare a SQL request and obtain SQL statement metadata
[ParamDataTypes.ts](https://github.com/Teradata/nodejs-driver/blob/develop/samples/ParamDataTypes.ts) | Demonstrates how to specify data types for parameter marker bind values
[ShowCommand.ts](https://github.com/Teradata/nodejs-driver/blob/develop/samples/ShowCommand.ts) | Displays the results from the `SHOW` command
[StoredProc.ts](https://github.com/Teradata/nodejs-driver/blob/develop/samples/StoredProc.ts) | Demonstrates how to create and call a SQL stored procedure
[TJEncryptPassword.ts](https://github.com/Teradata/nodejs-driver/blob/develop/samples/TJEncryptPassword.ts) | Creates encrypted password files
<a id="Using"></a>
### Using the Driver
Your JavaScript program must import the `teradatasql` package in order to use the driver.
const teradatasql = require("teradatasql");
After importing the `teradatasql` package, your JavaScript program calls the `teradatasql.connect` function to open a connection to the database.
const con = teradatasql.connect({
host: "whomooz",
user: "guest",
password: "please"
});
You may specify connection parameters as a JavaScript object, as a JSON string, or using a combination of the two approaches. The `teradatasql.connect` function's first argument is a JavaScript object. The `teradatasql.connect` function's second argument is an optional JSON string.
Connection parameters specified only as a JavaScript object:
con = teradatasql.connect({host:"whomooz",user:"guest",password:"please"});
Connection parameters specified as a JSON string:
con = teradatasql.connect({}, '{"host":"whomooz", "user":"guest", "password":"please"}');
Connection parameters specified using a combination:
con = teradatasql.connect({host:"whomooz"}, '{"user":"guest", "password":"please"}');
When a combination of parameters are specified, connection parameters specified as a JSON string take precedence over same-named connection parameters specified in the JavaScript object.
<a id="ConnectionParameters"></a>
### Connection Parameters
The following table lists the connection parameters currently offered by the driver. Connection parameter values are case-sensitive unless stated otherwise.
Our goal is consistency for the connection parameters offered by this driver and the Teradata JDBC Driver, with respect to connection parameter names and functionality. For comparison, Teradata JDBC Driver connection parameters are [documented here](https://downloads.teradata.com/doc/connectivity/jdbc/reference/current/jdbcug_chapter_2.html#BGBHDDGB).
Parameter | Default | Type | Description
----------------------- | ----------- | -------------- | ---
`account` | | string | Specifies the database account. Equivalent to the Teradata JDBC Driver `ACCOUNT` connection parameter.
`browser` | | string | Specifies the command to open the browser for Browser Authentication when `logmech` is `BROWSER`. Browser Authentication is supported for Windows and macOS. Equivalent to the Teradata JDBC Driver `BROWSER` connection parameter.<br/>The specified command must include a placeholder token, literally specified as `PLACEHOLDER`, which the driver will replace with the Identity Provider authorization endpoint URL. The `PLACEHOLDER` token is case-sensitive and must be specified in uppercase.<br/>• On Windows, the default command is `cmd /c start "title" "PLACEHOLDER"`. Windows command syntax requires the quoted title to precede the quoted URL.<br/>• On macOS, the default command is `open PLACEHOLDER`. macOS command syntax does not allow the URL to be quoted.
`browser_tab_timeout` | `"5"` | quoted integer | Specifies the number of seconds to wait before closing the browser tab after Browser Authentication is completed. The default is 5 seconds. The behavior is under the browser's control, and not all browsers support automatic closing of browser tabs. Typically, the tab used to log on will remain open indefinitely, but the second and subsequent tabs will be automatically closed. Specify `0` (zero) to close the tab immediately. Specify `-1` to turn off automatic closing of browser tabs. Browser Authentication is supported for Windows and macOS. Equivalent to the Teradata JDBC Driver `BROWSER_TAB_TIMEOUT` connection parameter.
`browser_timeout` | `"180"` | quoted integer | Specifies the number of seconds that the driver will wait for Browser Authentication to complete. The default is 180 seconds (3 minutes). Browser Authentication is supported for Windows and macOS. Equivalent to the Teradata JDBC Driver `BROWSER_TIMEOUT` connection parameter.
`code_append_file` | `"-out"` | string | Specifies how to display the verification URL and code. Optional when `logmech` is `CODE` and ignored for other `logmech` values. The default `-out` prints the verification URL and code to stdout. Specify `-err` to print the verification URL and code to stderr. Specify a file name to append the verification URL and code to an existing file or create a new file if the file does not exist. Equivalent to the Teradata JDBC Driver `CODE_APPEND_FILE` connection parameter.
`column_name` | `"false"` | quoted boolean | Controls the behavior of cursor `.description` sequence `name` items. Equivalent to the Teradata JDBC Driver `COLUMN_NAME` connection parameter. False specifies that a cursor `.description` sequence `name` item provides the AS-clause name if available, or the column name if available, or the column title. True specifies that a cursor `.description` sequence `name` item provides the column name if available, but has no effect when StatementInfo parcel support is unavailable.
`concurrent_interval` | `"1000"` | quoted integer | Specifies the interval in milliseconds for Laddered Concurrent Connect (LCC) to wait before starting another concurrent connection attempt.
`concurrent_limit` | `"3"` | quoted integer | Limits the number of concurrent connection attempts.
`connect_failure_ttl` | `"0"` | quoted integer | Specifies the time-to-live in seconds to remember the most recent connection failure for each IP address/port combination. The driver subsequently skips connection attempts to that IP address/port for the duration of the time-to-live. The default value of zero disables this feature. The recommended value is half the database restart time. Equivalent to the Teradata JDBC Driver `CONNECT_FAILURE_TTL` connection parameter.
`connect_function` | `"0"` | quoted integer | Specifies whether the database should allocate a Logon Sequence Number (LSN) for this session, or associate this session with an existing LSN. Specify `0` for a session with no LSN (the default). Specify `1` to allocate a new LSN for the session. Specify `2` to associate the session with the existing LSN identified by the `logon_sequence_number` connection parameter. The database only permits sessions for the same user to share an LSN. Equivalent to the Teradata JDBC Driver `CONNECT_FUNCTION` connection parameter.
`connect_timeout` | `"10000"` | quoted integer | Specifies the timeout in milliseconds for establishing a TCP socket connection. Specify `0` for no timeout. The default is 10 seconds (10000 milliseconds).
`cop` | `"true"` | quoted boolean | Specifies whether COP Discovery is performed. Equivalent to the Teradata JDBC Driver `COP` connection parameter.
`coplast` | `"false"` | quoted boolean | Specifies how COP Discovery determines the last COP hostname. Equivalent to the Teradata JDBC Driver `COPLAST` connection parameter. When `coplast` is `false` or omitted, or COP Discovery is turned off, then no DNS lookup occurs for the coplast hostname. When `coplast` is `true`, and COP Discovery is turned on, then a DNS lookup occurs for a coplast hostname.
`database` | | string | Specifies the initial database to use after logon, instead of the user's default database. Equivalent to the Teradata JDBC Driver `DATABASE` connection parameter.
`dbs_port` | `"1025"` | quoted integer | Specifies the database port number. Equivalent to the Teradata JDBC Driver `DBS_PORT` connection parameter.
`encryptdata` | `"false"` | quoted boolean | Controls encryption of data exchanged between the driver and the database. Equivalent to the Teradata JDBC Driver `ENCRYPTDATA` connection parameter.
`error_query_count` | `"21"` | quoted integer | Specifies how many times the driver will attempt to query FastLoad Error Table 1 after a FastLoad operation. Equivalent to the Teradata JDBC Driver `ERROR_QUERY_COUNT` connection parameter.
`error_query_interval` | `"500"` | quoted integer | Specifies how many milliseconds the driver will wait between attempts to query FastLoad Error Table 1. Equivalent to the Teradata JDBC Driver `ERROR_QUERY_INTERVAL` connection parameter.
`error_table_1_suffix` | `"_ERR_1"` | string | Specifies the suffix for the name of FastLoad Error Table 1. Equivalent to the Teradata JDBC Driver `ERROR_TABLE_1_SUFFIX` connection parameter.
`error_table_2_suffix` | `"_ERR_2"` | string | Specifies the suffix for the name of FastLoad Error Table 2. Equivalent to the Teradata JDBC Driver `ERROR_TABLE_2_SUFFIX` connection parameter.
`error_table_database` | | string | Specifies the database name for the FastLoad error tables. By default, FastLoad error tables reside in the same database as the destination table being loaded. Equivalent to the Teradata JDBC Driver `ERROR_TABLE_DATABASE` connection parameter.
`fake_result_sets` | `"false"` | quoted boolean | Controls whether a fake result set containing statement metadata precedes each real result set.
`field_quote` | `"\""` | string | Specifies a single character string used to quote fields in a CSV file.
`field_sep` | `","` | string | Specifies a single character string used to separate fields in a CSV file. Equivalent to the Teradata JDBC Driver `FIELD_SEP` connection parameter.
`govern` | `"true"` | quoted boolean | Controls FastLoad and FastExport throttling by Teradata workload management rules. When set to `true` (the default), workload management rules may delay a FastLoad or FastExport. When set to `false`, workload management rules will reject rather than delay a FastLoad or FastExport. Equivalent to the Teradata JDBC Driver `GOVERN` connection parameter.
`host` | | string | Specifies the database hostname.
`http_proxy` | | string | Specifies the proxy server URL for HTTP connections to TLS certificate verification CRL and OCSP endpoints. The URL must begin with `http://` and must include a colon `:` and port number.
`http_proxy_password` | | string | Specifies the proxy server password for the proxy server identified by the `http_proxy` parameter. This parameter may only be specified in conjunction with the `http_proxy` parameter. When this parameter is omitted, no proxy server password is provided to the proxy server identified by the `http_proxy` parameter.
`http_proxy_user` | | string | Specifies the proxy server username for the proxy server identified by the `http_proxy` parameter. This parameter may only be specified in conjunction with the `http_proxy` parameter. When this parameter is omitted, no proxy server username is provided to the proxy server identified by the `http_proxy` parameter.
`https_port` | `"443"` | quoted integer | Specifies the database port number for HTTPS/TLS connections. Equivalent to the Teradata JDBC Driver `HTTPS_PORT` connection parameter.
`https_proxy` | | string | Specifies the proxy server URL for HTTPS/TLS connections to the database and to Identity Provider endpoints. The URL must begin with `http://` and must include a colon `:` and port number. The driver connects to the proxy server using a non-TLS HTTP connection, then uses the HTTP CONNECT method to establish an HTTPS/TLS connection to the destination. Equivalent to the Teradata JDBC Driver `HTTPS_PROXY` connection parameter.
`https_proxy_password` | | string | Specifies the proxy server password for the proxy server identified by the `https_proxy` parameter. This parameter may only be specified in conjunction with the `https_proxy` parameter. When this parameter is omitted, no proxy server password is provided to the proxy server identified by the `https_proxy` parameter. Equivalent to the Teradata JDBC Driver `HTTPS_PROXY_PASSWORD` connection parameter.
`https_proxy_user` | | string | Specifies the proxy server username for the proxy server identified by the `https_proxy` parameter. This parameter may only be specified in conjunction with the `https_proxy` parameter. When this parameter is omitted, no proxy server username is provided to the proxy server identified by the `https_proxy` parameter. Equivalent to the Teradata JDBC Driver `HTTPS_PROXY_USER` connection parameter.
`jws_algorithm` | `"RS256"` | string | Specifies the JSON Web Signature (JWS) algorithm to sign the JWT Bearer Token for client authentication. Optional when `logmech` is `BEARER` and ignored for other `logmech` values. The default `RS256` is RSASSA-PKCS1-v1_5 using SHA-256. Specify `RS384` for RSASSA-PKCS1-v1_5 using SHA-384. Specify `RS512` for RSASSA-PKCS1-v1_5 using SHA-512. Equivalent to the Teradata JDBC Driver `JWS_ALGORITHM` connection parameter.
`jws_cert` | | string | Specifies the file name of the X.509 certificate PEM file that contains the public key corresponding to the private key from `jws_private_key`. Optional when `logmech` is `BEARER` and ignored for other `logmech` values. When this parameter is specified, the "x5t" header thumbprint is added to the JWT Bearer Token for the Identity Provider to select the public key for JWT signature verification. Some Identity Providers, such as Microsoft Entra ID, require this. When this parameter is omitted, the "x5t" header thumbprint is not added to the JWT Bearer Token. Some Identity Providers do not require the "x5t" header thumbprint. Equivalent to the Teradata JDBC Driver `JWS_CERT` connection parameter.
`jws_private_key` | | string | Specifies the file name of the PEM or JWK file containing the private key to sign the JWT Bearer Token for client authentication. Required when `logmech` is `BEARER` and ignored for other `logmech` values. PEM and JWK file formats are supported. The private key filename must end with the `.pem` or `.jwk` extension. A PEM file must contain the BEGIN/END PRIVATE KEY header and trailer. If a JWK file contains a "kid" (key identifier) parameter, the "kid" header is added to the JWT Bearer Token for the Identity Provider to select the public key for JWT signature verification. Equivalent to the Teradata JDBC Driver `JWS_PRIVATE_KEY` connection parameter.
`lob_support` | `"true"` | quoted boolean | Controls LOB support. Equivalent to the Teradata JDBC Driver `LOB_SUPPORT` connection parameter.
`log` | `"0"` | quoted integer | Controls debug logging. Somewhat equivalent to the Teradata JDBC Driver `LOG` connection parameter. This parameter's behavior is subject to change in the future. This parameter's value is currently defined as an integer in which the 1-bit governs function and method tracing, the 2-bit governs debug logging, the 4-bit governs transmit and receive message hex dumps, and the 8-bit governs timing. Compose the value by adding together 1, 2, 4, and/or 8.
`logdata` | | string | Specifies extra data for the chosen logon authentication method. Equivalent to the Teradata JDBC Driver `LOGDATA` connection parameter.
`logmech` | `"TD2"` | string | Specifies the [logon authentication method](#LogonMethods). Equivalent to the Teradata JDBC Driver `LOGMECH` connection parameter. The database user must have the "logon with null password" permission for `KRB5` Single Sign On (SSO) or any of the [OpenID Connect (OIDC)](https://en.wikipedia.org/wiki/OpenID#OpenID_Connect_(OIDC)) methods `BEARER`, `BROWSER`, `CODE`, `CRED`, `JWT`, `ROPC`, or `SECRET`. [GSS-API](https://en.wikipedia.org/wiki/Generic_Security_Services_Application_Program_Interface) methods are `KRB5`, `LDAP`, `TD2`, and `TDNEGO`. Values are case-insensitive.<br/>• `BEARER` uses OIDC Client Credentials Grant with JWT Bearer Token for client authentication.<br/>• `BROWSER` uses Browser Authentication, supported for Windows and macOS.<br/>• `CODE` uses OIDC Device Code Flow, also known as OIDC Device Authorization Grant.<br/>• `CRED` uses OIDC Client Credentials Grant with client_secret_post for client authentication.<br/>• `JWT` uses JSON Web Token.<br/>• `KRB5` uses Kerberos V5.<br/>• `LDAP` uses Lightweight Directory Access Protocol.<br/>• `ROPC` uses OIDC Resource Owner Password Credentials (ROPC).<br/>• `SECRET` uses OIDC Client Credentials Grant with client_secret_basic for client authentication.<br/>• `TD2` uses Teradata Method 2.<br/>• `TDNEGO` automatically selects an appropriate GSS-API logon authentication method. OIDC methods are not selected.
`logon_sequence_number` | | quoted integer | Associates this session with an existing Logon Sequence Number (LSN) when `connect_function` is `2`. The database only permits sessions for the same user to share an LSN. An LSN groups multiple sessions together for workload management. Using an LSN is a three-step process. First, establish a control session with `connect_function` as `1`, which allocates a new LSN. Second, obtain the LSN from the control session using the escape function `{fn teradata_logon_sequence_number}`. Third, establish an associated session with `connect_function` as `2` and the logon sequence number. Equivalent to the Teradata JDBC Driver `LOGON_SEQUENCE_NUMBER` connection parameter.
`logon_timeout` | `"0"` | quoted integer | Specifies the logon timeout in seconds. Zero means no timeout.
`manage_error_tables` | `"true"` | quoted boolean | Controls whether the driver manages the FastLoad error tables.
`max_message_body` | `"2097000"` | quoted integer | Specifies the maximum Response Message size in bytes. Equivalent to the Teradata JDBC Driver `MAX_MESSAGE_BODY` connection parameter.
`oauth_level` | `"0"` | quoted integer | Controls Single Sign On (SSO) access to Open Table Format (OTF) catalog and storage instances. Equivalent to the Teradata JDBC Driver `OAUTH_LEVEL` connection parameter. If `redrive` is `1` or higher and the database supports Control Data, this specifies which tokens are transmitted to the database with each request, and the database may use the tokens for SSO access to OTF catalog and storage instances. If `redrive` is `0` or the database does not support Control Data, tokens are not transmitted to the database with each request, and tokens will not be available for SSO access to OTF. <br/>• `0` (the default) disables sending tokens to the database. <br/>• `1` sends the token from OIDC authentication to the database for each SQL request. <br/>• `2` sends the OAuth tokens from `oauth_scopes` to the database for each SQL request. <br/>• `3` sends the token from OIDC authentication and the OAuth tokens to the database for each SQL request.
`oauth_scopes` | | string | Specifies one or more OAuth scopes for SSO access to OTF catalog and storage instances. Multiple scopes are separated by vertical bar `\|` characters. This parameter may only be used with OIDC logon mechanisms for individual users, not for service accounts. When this parameter is specified, after successful OIDC authentication, the driver obtains an additional access token from the Identity Provider for each specified scope. Each additional access token request uses the same OIDC parameters as the initial OIDC authentication; only the scope is varied. Equivalent to the Teradata JDBC Driver `OAUTH_SCOPES` connection parameter.
`oidc_cache_size` | `"20"` | quoted integer | Specifies the maximum size of the OpenID Connect (OIDC) token cache for Browser Authentication and other OIDC methods. Equivalent to the Teradata JDBC Driver `OIDC_CACHE_SIZE` connection parameter.
`oidc_claim` | `"email"` | string | Specifies the OpenID Connect (OIDC) claim to use for Browser Authentication and other OIDC methods. Equivalent to the Teradata JDBC Driver `OIDC_CLAIM` connection parameter.
`oidc_clientid` | | string | Specifies the OpenID Connect (OIDC) Client ID to use for Browser Authentication and other OIDC methods. When omitted, the default Client ID comes from the database's TdgssUserConfigFile.xml file. Browser Authentication is supported for Windows and macOS. Equivalent to the Teradata JDBC Driver `OIDC_CLIENTID` connection parameter.
`oidc_metadata` | | string | Specifies the Identity Provider metadata URL for OpenID Connect (OIDC). When this connection parameter is omitted, the default metadata URL is provided by the database. This connection parameter is a troubleshooting tool only, and is not intended for normal production usage. Equivalent to the Teradata JDBC Driver `OIDC_METADATA` connection parameter.
`oidc_prompt` | | string | Specifies the OpenID Connect (OIDC) prompt value to use for Browser Authentication. Optional when `logmech` is `BROWSER` and ignored for other `logmech` values. Ignored unless `user` is specified as an OIDC login hint. Specify `login` for the Identity Provider to prompt the user for credentials. May not be supported by all Identity Providers. The browser tab may not close automatically after Browser Authentication is completed. Equivalent to the Teradata JDBC Driver `OIDC_PROMPT` connection parameter.
`oidc_scope` | `"openid"` | string | Specifies the OpenID Connect (OIDC) scope to use for Browser Authentication. Beginning with Teradata Database 17.20.03.11, the default scope can be specified in the database's `TdgssUserConfigFile.xml` file, using the `IdPConfig` element's `Scope` attribute. Browser Authentication is supported for Windows and macOS. Equivalent to the Teradata JDBC Driver `OIDC_SCOPE` connection parameter.
`oidc_sslmode` | | string | Specifies the mode for HTTPS connections to the Identity Provider. Equivalent to the Teradata JDBC Driver `OIDC_SSLMODE` connection parameter. Values are case-insensitive. When this parameter is omitted, the default is the value of the `sslmode` connection parameter.<br/>• `ALLOW` does not perform certificate verification for HTTPS connections to the Identity Provider.<br/>• `VERIFY-CA` verifies that the server certificate is valid and trusted.<br/>• `VERIFY-FULL` verifies that the server certificate is valid and trusted, and verifies that the server certificate matches the Identity Provider hostname.
`oidc_token` | `"access_token"` | string | Specifies the kind of OIDC token to use for Browser Authentication. Specify `id_token` to use the id_token instead of the access_token. Browser Authentication is supported for Windows and macOS. Equivalent to the Teradata JDBC Driver `OIDC_TOKEN` connection parameter.
`partition` | `"DBC/SQL"` | string | Specifies the database partition. Equivalent to the Teradata JDBC Driver `PARTITION` connection parameter.
`password` | | string | Specifies the database password. Equivalent to the Teradata JDBC Driver `PASSWORD` connection parameter.
`proxy_bypass_hosts` | | string | Specifies a matching pattern for hostnames and addresses to bypass the proxy server identified by the `http_proxy` and/or `https_proxy` parameter. This parameter may only be specified in conjunction with the `http_proxy` and/or `https_proxy` parameter. Separate multiple hostnames and addresses with a vertical bar `\|` character. Specify an asterisk `*` as a wildcard character. When this parameter is omitted, the default pattern `localhost\|127.*\|[::1]` bypasses the proxy server identified by the `http_proxy` and/or `https_proxy` parameter for common variations of the loopback address. Equivalent to the Teradata JDBC Driver `PROXY_BYPASS_HOSTS` connection parameter.
`request_timeout` | `"0"` | quoted integer | Specifies the timeout for executing each SQL request. Zero means no timeout.
`runstartup` | `"false"` | quoted boolean | Controls whether the user's `STARTUP` SQL request is executed after logon. For more information, refer to [User STARTUP SQL Request](#UserStartup). Equivalent to the Teradata JDBC Driver `RUNSTARTUP` connection parameter.
`sessions` | | quoted integer | Specifies the number of data transfer connections for FastLoad or FastExport. The default (recommended) lets the database choose the appropriate number of connections. Equivalent to the Teradata JDBC Driver `SESSIONS` connection parameter.
`sip_support` | `"true"` | quoted boolean | Controls whether StatementInfo parcel is used. Equivalent to the Teradata JDBC Driver `SIP_SUPPORT` connection parameter.
`sp_spl` | `"true"` | quoted boolean | Controls whether stored procedure source code is saved in the database when a SQL stored procedure is created. Equivalent to the Teradata JDBC Driver `SP_SPL` connection parameter.
`sslca` | | string | Specifies the file name of a PEM file that contains Certificate Authority (CA) certificates for use with `sslmode` or `oidc_sslmode` values `VERIFY-CA` or `VERIFY-FULL`. Equivalent to the Teradata JDBC Driver `SSLCA` connection parameter.
`sslcapath` | | string | Specifies a directory of PEM files that contain Certificate Authority (CA) certificates for use with `sslmode` or `oidc_sslmode` values `VERIFY-CA` or `VERIFY-FULL`. Only files with an extension of `.pem` are used. Other files in the specified directory are not used. Equivalent to the Teradata JDBC Driver `SSLCAPATH` connection parameter.
`sslcipher` | | string | Specifies the TLS cipher for HTTPS/TLS connections. Default lets database and driver choose the most appropriate TLS cipher. Equivalent to the Teradata JDBC Driver `SSLCIPHER` connection parameter.
`sslcrc` | `"ALLOW"` | string | Controls TLS certificate revocation checking (CRC) for HTTPS/TLS connections. Equivalent to the Teradata JDBC Driver `SSLCRC` connection parameter. Values are case-insensitive.<br/>• `ALLOW` performs CRC for `sslmode` or `oidc_sslmode` `VERIFY-CA` and `VERIFY-FULL`, and provides soft fail CRC for `VERIFY-CA` and `VERIFY-FULL` to ignore CRC communication failures.<br/>• `PREFER` performs CRC for all HTTPS connections, and provides soft fail CRC for `VERIFY-CA` and `VERIFY-FULL` to ignore CRC communication failures.<br/>• `REQUIRE` performs CRC for all HTTPS connections, and requires CRC for `VERIFY-CA` and `VERIFY-FULL`.
`sslcrl` | `"true"` | quoted boolean | Controls the use of Certificate Revocation List (CRL) for TLS certificate revocation checking for HTTPS/TLS connections. Online Certificate Status Protocol (OCSP) is preferred over CRL, so CRL is used when OSCP is unavailable. Equivalent to the Teradata JDBC Driver `SSLCRL` connection parameter.
`sslmode` | `"PREFER"` | string | Specifies the mode for connections to the database. Equivalent to the Teradata JDBC Driver `SSLMODE` connection parameter. Values are case-insensitive.<br/>• `DISABLE` disables HTTPS/TLS connections and uses only non-TLS connections.<br/>• `ALLOW` uses non-TLS connections unless the database requires HTTPS/TLS connections.<br/>• `PREFER` uses HTTPS/TLS connections unless the database does not offer HTTPS/TLS connections.<br/>• `REQUIRE` uses only HTTPS/TLS connections.<br/>• `VERIFY-CA` uses only HTTPS/TLS connections and verifies that the server certificate is valid and trusted.<br/>• `VERIFY-FULL` uses only HTTPS/TLS connections, verifies that the server certificate is valid and trusted, and verifies that the server certificate matches the database hostname.
`sslnamedgroups` | | string | Specifies the TLS key exchange named groups for HTTPS/TLS connections. Multiple named groups are separated by commas. Default lets database and driver choose the most appropriate named group. Equivalent to the Teradata JDBC Driver `SSLNAMEDGROUPS` connection parameter.
`sslocsp` | `"true"` | quoted boolean | Controls the use of Online Certificate Status Protocol (OCSP) for TLS certificate revocation checking for HTTPS/TLS connections. Equivalent to the Teradata JDBC Driver `SSLOCSP` connection parameter.
`sslprotocol` | `"TLSv1.2"` | string | Specifies the TLS protocol for HTTPS/TLS connections. Equivalent to the Teradata JDBC Driver `SSLPROTOCOL` connection parameter.
`teradata_values` | `"true"` | quoted boolean | Controls whether `str` or a more specific JavaScript data type is used for certain result set column value types. Refer to the [Data Types](#DataTypes) table below for details.
`tmode` | `"DEFAULT"` | string | Specifies the [transaction mode](#TransactionMode). Equivalent to the Teradata JDBC Driver `TMODE` connection parameter. Possible values are `DEFAULT` (the default), `ANSI`, or `TERA`.
`user` | | string | Specifies the database username. Equivalent to the Teradata JDBC Driver `USER` connection parameter.
<a id="COPDiscovery"></a>
### COP Discovery
The driver provides Communications Processor (COP) discovery behavior when the `cop` connection parameter is `true` or omitted. COP Discovery is turned off when the `cop` connection parameter is `false`.
A database system can be composed of multiple database nodes. One or more of the database nodes can be configured to run the database Gateway process. Each database node that runs the database Gateway process is termed a Communications Processor, or COP. COP Discovery refers to the procedure of identifying all the available COP hostnames and their IP addresses. COP hostnames can be defined in DNS, or can be defined in the client system's `hosts` file. Teradata strongly recommends that COP hostnames be defined in DNS, rather than the client system's `hosts` file. Defining COP hostnames in DNS provides centralized administration, and enables centralized changes to COP hostnames if and when the database is reconfigured.
The `coplast` connection parameter specifies how COP Discovery determines the last COP hostname.
* When `coplast` is `false` or omitted, or COP Discovery is turned off, then the driver will not perform a DNS lookup for the coplast hostname.
* When `coplast` is `true`, and COP Discovery is turned on, then the 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 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.
Specifying `coplast` as `true` can improve performance with DNS that is slow to respond for DNS lookup failures, and is necessary for DNS that never returns a DNS lookup failure.
When performing COP Discovery, the driver starts with cop1, which is appended to the database hostname, and then proceeds with cop2, cop3, ..., copN. The driver supports domain-name qualification for COP Discovery and the coplast hostname. Domain-name qualification is recommended, because it can improve performance by avoiding unnecessary DNS lookups for DNS search suffixes.
The following table illustrates the DNS lookups performed for a hypothetical three-node database system named "whomooz".
| No domain name qualification | With domain name qualification<br/>(Recommended)
------ | ---------------------------- | ---
Application-specified<br/>database hostname | `whomooz` | `whomooz.domain.com`
Default: COP Discovery turned on, and `coplast` is `false` or omitted,<br/>perform DNS lookups until unknown COP hostname is encountered | `whomoozcop1`→`10.0.0.1`<br/>`whomoozcop2`→`10.0.0.2`<br/>`whomoozcop3`→`10.0.0.3`<br/>`whomoozcop4`→undefined | `whomoozcop1.domain.com`→`10.0.0.1`<br/>`whomoozcop2.domain.com`→`10.0.0.2`<br/>`whomoozcop3.domain.com`→`10.0.0.3`<br/>`whomoozcop4.domain.com`→undefined
COP Discovery turned on, and `coplast` is `true`,<br/>perform DNS lookups until COP hostname is found whose IP address matches the coplast hostname, or unknown COP hostname is encountered | `whomoozcoplast`→`10.0.0.3`<br/>`whomoozcop1`→`10.0.0.1`<br/>`whomoozcop2`→`10.0.0.2`<br/>`whomoozcop3`→`10.0.0.3` | `whomoozcoplast.domain.com`→`10.0.0.3`<br/>`whomoozcop1.domain.com`→`10.0.0.1`<br/>`whomoozcop2.domain.com`→`10.0.0.2`<br/>`whomoozcop3.domain.com`→`10.0.0.3`
COP Discovery turned off and round-robin DNS,<br/>perform one DNS lookup that returns multiple IP addresses | `whomooz`→`10.0.0.1`, `10.0.0.2`, `10.0.0.3` | `whomooz.domain.com`→`10.0.0.1`, `10.0.0.2`, `10.0.0.3`
Round-robin DNS rotates the list of IP addresses automatically to provide load distribution. Round-robin is only possible with DNS, not with the client system `hosts` file.
The driver supports the definition of multiple IP addresses for COP hostnames and non-COP hostnames.
For the first connection to a particular database system, the driver generates a random number to index into the list of COPs. For each subsequent connection, the driver increments the saved index until it wraps around to the first position. This behavior provides load distribution across all discovered COPs.
The driver masks connection failures to down COPs, thereby hiding most connection failures from the client application. An exception is thrown to the application only when all the COPs are down for that database. If a COP is down, the next COP in the sequence (including a wrap-around to the first COP) receives extra connections that were originally destined for the down COP. When multiple IP addresses are defined in DNS for a COP, the driver will attempt to connect to each of the COP's IP addresses, and the COP is considered down only when connection attempts fail to all of the COP's IP addresses.
If COP Discovery is turned off, or no COP hostnames are defined in DNS, the driver connects directly to the hostname specified in the `host` connection parameter. This permits load distribution schemes other than the COP Discovery approach. For example, round-robin DNS or a TCP/IP load distribution product can be used. COP Discovery takes precedence over simple database hostname lookup. To use an alternative load distribution scheme, either ensure that no COP hostnames are defined in DNS, or turn off COP Discovery with `cop` as `false`.
<a id="StoredPasswordProtection"></a>
### Stored Password Protection
#### Overview
Stored Password Protection enables an application to provide a connection password in encrypted form to the driver.
An encrypted password may be specified in the following contexts:
* A login password specified as the `password` connection parameter.
* A login password specified within the `logdata` connection parameter.
If the password, however specified, begins with the prefix `ENCRYPTED_PASSWORD(` then the specified password must follow this format:
`ENCRYPTED_PASSWORD(file:`*PasswordEncryptionKeyFileName*`,file:`*EncryptedPasswordFileName*`)`
Each filename must be preceded by the `file:` prefix. The *PasswordEncryptionKeyFileName* must be separated from the *EncryptedPasswordFileName* by a single comma.
The *PasswordEncryptionKeyFileName* specifies the name of a file that contains the password encryption key and associated information. The *EncryptedPasswordFileName* specifies the name of a file that contains the encrypted password and associated information. The two files are described below.
Stored Password Protection is offered by this driver, the Teradata JDBC Driver, and the Teradata SQL Driver for R. These drivers use the same file format.
#### Program TJEncryptPassword.ts
`TJEncryptPassword.ts` is a sample program to create encrypted password files for use with Stored Password Protection. When the driver is installed, the sample programs are placed in the `teradatasql/samples` directory under your `node_modules` installation directory.
This program works in conjunction with Stored Password Protection offered by the driver. This program creates the files containing the password encryption key and encrypted password, which can be subsequently specified via the `ENCRYPTED_PASSWORD(` syntax.
You are not required to use this program to create the files containing the password encryption key and encrypted password. You can develop your own software to create the necessary files. You may also use the [`TJEncryptPassword.java`](https://downloads.teradata.com/doc/connectivity/jdbc/reference/current/samp/TJEncryptPassword.java.txt) sample program that is available with the [Teradata JDBC Driver Reference](h