ArpeTeradata — Connection guide

Everything you can set to point ArpeTeradata at a Teradata server, in one place: every option the driver accepts, its default and effect, how transactions and cancel behave, and the environment variables the driver reads.

For how the logon works, when TLS is used and when TTU must be installed, see Authentication. For the licence, see Licensing.

The logon happens at connect

AdbcConnectionInit (Python's dbapi.connect()) opens the socket and logs on. A wrong host, password or TLS setting, or a missing TTU, is therefore reported by the connect call itself.

Three ways to connect

Like every driver of the family, ArpeTeradata accepts three connection forms. They can be mixed: a discrete option always wins over the same field taken from a connection string or a URI, whatever the order they are set. Since v0.3.5; earlier releases accept discrete options only.

Form	Option key	Grammar	Best for
Discrete options	`adbc.arpeteradata.<field>`	one option per field	programmatic clients, secrets kept out of a single string
Connection string	`adbc.arpeteradata.connection_string` (alias `connection_string`)	ADO.NET `Key=Value;…`	pasting a .NET connection string
Connection URI	`uri` (alias `adbc.arpeteradata.uri`)	`teradata://…` URL	configuration files, portable tooling, SQLAlchemy-style URLs

Python
import adbc_driver_manager.dbapi as dbapi

# Discrete options
conn = dbapi.connect(driver="arpeteradata", db_kwargs={
    "adbc.arpeteradata.server":   "td.example.com",
    "adbc.arpeteradata.database": "SALES",
    "adbc.arpeteradata.username": "alice",
    "adbc.arpeteradata.password": "<pw>",
    "adbc.arpeteradata.sslmode":  "verify-full",
}, autocommit=True)

# Connection string (ADO.NET keywords)
conn = dbapi.connect(driver="arpeteradata", db_kwargs={
    "adbc.arpeteradata.connection_string":
        "Data Source=td.example.com;Database=SALES;User ID=alice;Password=<pw>;sslmode=verify-full",
}, autocommit=True)

# Connection URI
conn = dbapi.connect(driver="arpeteradata", db_kwargs={
    "uri": "teradata://alice:<pw>@td.example.com/SALES?sslmode=verify-full",
}, autocommit=True)

with conn, conn.cursor() as cur:
    cur.execute("SELECT * FROM SALES.ORDERS SAMPLE 10")
    print(cur.fetch_arrow_table())

server is always required, and so is username for a TD2 logon (the default). A connection made without them fails with logon requires adbc.arpeteradata.server and username. The licence options (arpeio.adbc.license, arpeio.adbc.license_file) are always discrete.

Choosing TLS or the legacy port in a URI

sslmode works in every form: teradata://alice:<pw>@td.example.com/?sslmode=disable logs on through TTU CLIv2 on the legacy port, ?sslmode=require (or verify-ca, verify-full) over TLS only. See Authentication.

Precedence and errors. The connection string or URI is read when the database is initialised (AdbcDatabaseInit). Each field it gives is applied only if no discrete option set that field, and goes through the same checks as the option itself. Setting both uri and connection_string, a malformed value, an unknown key, or a field given twice fails AdbcDatabaseInit with INVALID_ARGUMENT and a message naming the offending part. A password is never put in an error message, and GetOption on uri or connection_string returns the value with the password and logdata shown as ***. The stored value is wiped from memory when it is replaced and when the database is released.

URI

teradata://[user[:password]@]host[:port][/database][?key=value&…]

Schemes (case-insensitive): teradata, arpeteradata and teradatasql (the scheme of Teradata's SQLAlchemy dialect, so an existing URL can be pasted as is). Any other scheme is refused.
The host is required. An IPv6 address goes in brackets: teradata://alice@[2001:db8::1]:1025/SALES.
port is the legacy (DBS) port, default 1025. The TLS port is the https_port query key (default 443).
The path is the default database.
Percent-encoding: user, password, the host, the database and query values are percent-decoded, so characters such as @ : / ? # & % + in a password are written %40 %3A %2F %3F %23 %26 %25 %2B. In a query value + is a space.

Query keys (case-insensitive), each setting the matching adbc.arpeteradata.* option:

Query key	Option
`user`, `username`	`username`
`password`	`password`
`database`	`database`
`dbs_port`, `port`	`port`
`charset`, `tmode`	same name
`login_timeout`, `logon_timeout`	`login_timeout`
`query_timeout`	`query_timeout`
`batch_size`, `buffer_size`	`batch_size`
`sslmode`, `https_port`, `sslca`, `sslcapath`	same name
`ttu_path`	`ttu_path`
`logmech`, `logdata`, `kerberos_spn`	same name

teradatasql's encryptdata, connect_timeout and request_timeout have no equivalent in this driver and are refused as unknown keys.

Connection string

Key=Value pairs separated by ;. Keys are case-insensitive, and spaces and underscores in them are ignored (Data Source = DataSource = data_source). A value may be quoted with '…' or "…", inside which ; and = are literal and a doubled quote is one quote: Password='a;b''c' is the password a;b'c.

Keys	Option
`Server`, `Host`, `Hostname`, `Data Source`, `Address`	`server`
`Port`, `DBS Port`, `Port Number`	`port`
`Database`, `Initial Catalog`	`database`
`User ID`, `User`, `Username`, `UID`	`username`
`Password`, `PWD`	`password`
`Charset`	`charset`
`TMode`, `Session Mode`	`tmode`
`Login Timeout`, `Logon Timeout`, `Connect Timeout`, `Connection Timeout`	`login_timeout`
`Query Timeout`	`query_timeout`
`Batch Size`, `Buffer Size`	`batch_size`
`sslmode`, `HTTPS Port`, `sslca`, `sslcapath`	same name
`TTU Path`	`ttu_path`
`LogMech`, `Authentication Mechanism`	`logmech`
`LogData`, `Authentication String`	`logdata`
`Kerberos SPN`	`kerberos_spn`

In both forms, ports must be integers from 1 to 65535 and timeouts whole numbers of seconds.

Teradata cloud environments

A Teradata environment in the cloud is reached like any other Teradata server: by its host name, over TLS on port 443 or on the legacy port 1025. The steps below were checked against an environment of Teradata's free trial (trial.teradata.com), Teradata 20.00.

What you need

The host name. In the environment's dashboard, open the environment and its connection details. A trial host looks like <name>-<id>.env.trial.teradata.com.
A user and its password. On the trial, the user is demo_user and the password is the one chosen when the environment was created. Its default database is DEMO_USER, where it can create tables.
A running environment. A trial environment is suspended after a period of inactivity and has to be resumed from the dashboard before it accepts connections.

Which port and `sslmode`

Path	Port	`sslmode`	Needs TTU	Notes
TLS logon	443	`require`	no	Recommended: encrypted, no client software besides the driver.
Legacy port	1025	`disable`	yes, TTU CLIv2	Not encrypted.

Use sslmode=require rather than the default prefer: prefer falls back to the unencrypted legacy port when the TLS logon fails, which over the internet is rarely what you want.

Certificate verification on the trial

The trial's TLS certificate is issued to trial.teradata.com by a Teradata CA that the server does not send and that public trust stores do not hold, so verify-ca and verify-full fail with TLS certificate verification failed: unable to get local issuer certificate. require encrypts the session without checking the certificate, and prints a one-time warning saying so (ARPETERADATA_NO_TLS_WARNING=1 silences it). For an environment whose certificate chains to a CA you trust, use verify-full, with that CA in adbc.arpeteradata.sslca if it is not in the system store.

Connect

Every connection form works. Each example below connects to the trial over TLS:

Python — discrete options
import adbc_driver_manager.dbapi as dbapi

conn = dbapi.connect(driver="arpeteradata", db_kwargs={
    "adbc.arpeteradata.server":   "<name>-<id>.env.trial.teradata.com",
    "adbc.arpeteradata.username": "demo_user",
    "adbc.arpeteradata.password": "<pw>",
    "adbc.arpeteradata.sslmode":  "require",
}, autocommit=True)

Python — URI
# Percent-encode the password if it holds @ : / ? # & % or +
# (urllib.parse.quote(pw, safe="")), or leave it out of the URI and pass
# adbc.arpeteradata.password separately.
conn = dbapi.connect(driver="arpeteradata", db_kwargs={
    "uri": "teradata://demo_user:<pw>@<name>-<id>.env.trial.teradata.com/demo_user?sslmode=require",
}, autocommit=True)

Python — connection string
conn = dbapi.connect(driver="arpeteradata", db_kwargs={
    "adbc.arpeteradata.connection_string":
        "Host=<name>-<id>.env.trial.teradata.com;User ID=demo_user;Password='<pw>';sslmode=require",
}, autocommit=True)

Python — legacy port through TTU
conn = dbapi.connect(driver="arpeteradata", db_kwargs={
    "uri": "teradata://demo_user:<pw>@<name>-<id>.env.trial.teradata.com:1025?sslmode=disable",
}, autocommit=True)

DuckDB (adbc_scanner community extension)
INSTALL adbc_scanner FROM community;
LOAD adbc_scanner;

SET VARIABLE td = adbc_connect({
    'driver': 'arpeteradata',
    'uri': 'teradata://demo_user:<pw>@<name>-<id>.env.trial.teradata.com/demo_user?sslmode=require'
});
SELECT * FROM adbc_scan(getvariable('td'), 'SELECT * FROM DBC.DBCInfoV');

-- Or attach the database as a catalog:
ATTACH '' AS td (TYPE adbc, driver 'arpeteradata',
    uri 'teradata://demo_user:<pw>@<name>-<id>.env.trial.teradata.com/demo_user?sslmode=require');
SELECT count(*) FROM td.demo_user.nation;

C#
using AdbcDriver driver = CAdbcDriverImporter.Load(
    "libarpeteradata_adbc_driver-linux-x64.so", "AdbcDriverInit");
using AdbcDatabase database = driver.Open(new Dictionary<string, string> {
    ["adbc.arpeteradata.server"]   = "<name>-<id>.env.trial.teradata.com",
    ["adbc.arpeteradata.username"] = "demo_user",
    ["adbc.arpeteradata.password"] = "<pw>",
    ["adbc.arpeteradata.sslmode"]  = "require",
});
using AdbcConnection connection = database.Connect(null);

The other ADBC clients (C/C++, Go, Java, R, Rust) take the same options: see Examples.

Check the connection

with conn.cursor() as cur:
    cur.execute("SELECT InfoData FROM DBC.DBCInfoV WHERE InfoKey = 'VERSION'")
    print(cur.fetchone())           # ('20.00.24.60',)
    cur.execute("SELECT SESSION, USER, DATABASE")
    print(cur.fetchone())           # (1009, 'DEMO_USER', 'DEMO_USER')

Load, query and extract

Bulk ingest, queries and reads work as on any Teradata server; see Bulk ingest and Export a query to Parquet. Over the internet, a load is bound by the upload bandwidth of your network and a read by its download bandwidth.

Option reference

All options are string-typed and live under the adbc.arpeteradata.* namespace, except the ADBC-standard and licence keys. An unknown database option is rejected (NOT_IMPLEMENTED, Unknown database option: …).

Target and credentials

Option	Default	Meaning
`adbc.arpeteradata.server`	— (required)	Host name or IP address of the Teradata gateway.
`adbc.arpeteradata.port`	1025	TCP port of the legacy (non-TLS) gateway port.
`adbc.arpeteradata.database` (alias `adbc.connection.catalog`)	the user's own database	Default database of the session, applied right after logon (`DATABASE <name>`). An unknown database fails the connect.
`adbc.arpeteradata.username` (alias `username`)	—	Teradata user; for `logmech=LDAP`, the directory user. Required for TD2. Not needed with `logmech` `JWT`, `KRB5` or `TDNEGO`, nor with LDAP credentials in `logdata`.
`adbc.arpeteradata.password` (alias `password`)	empty	Password. Any character is safe (commas, spaces, quotes, non-ASCII): the driver quotes it in the logon.

Logon mechanism

Full detail is in Authentication → Logon mechanisms.

Option	Values	Meaning
`adbc.arpeteradata.logmech`	`TD2` (default) / `LDAP` / `KRB5` / `TDNEGO` / `JWT`	Logon mechanism, not case-sensitive. Any other value is rejected (`INVALID_ARGUMENT`). Since v0.3.4.
`adbc.arpeteradata.logdata`	string, up to 65535 bytes	Mechanism data, as in bteq's `.logdata`: `token=<JWT>` for JWT (required), or `authcid=<user> password=<password>` for LDAP. A secret: never returned by `GetOption`. Since v0.3.4.
`adbc.arpeteradata.kerberos_spn`	string, up to 511 bytes	Kerberos service principal for the TLS logon with `KRB5` / `TDNEGO`. Default `TERADATA/<server>` in the default realm. Set it when `server` is an IP address or a DNS alias, e.g. `TERADATA/td.example.com@EXAMPLE.COM`. No effect on the legacy port. Since v0.3.4.

Encryption / TLS

Option	Default	Meaning
`adbc.arpeteradata.sslmode`	`prefer`	`disable` / `allow` / `prefer` / `require` / `verify-ca` / `verify-full` (not case-sensitive). See the table below. Since v0.2.4.
`adbc.arpeteradata.https_port`	443	Port of the gateway's HTTPS (TLS) listener, `1..65535`. Since v0.2.4.
`adbc.arpeteradata.sslca`	—	PEM file of trusted CA certificates, for `verify-ca` / `verify-full`. At most 1023 bytes. Since v0.2.4.
`adbc.arpeteradata.sslcapath`	—	Directory of PEM CA certificates, for `verify-ca` / `verify-full`. At most 1023 bytes. Since v0.2.4.
`adbc.arpeteradata.ttu_path`	—	Directory holding your TTU CLIv2 library (`libcliv2.so` on Linux, `wincli32.dll` on Windows), for the legacy-port logon. Searched first. See Where the driver looks for TTU. Since v0.3.0.

`sslmode`	Tries	Falls back	Verifies the server
`disable`	legacy port (TTU)	—	—
`allow`	legacy port first	to TLS	no
`prefer` (default)	TLS first	to the legacy port (TTU)	no
`require`	TLS only	no	no
`verify-ca`	TLS only	no	certificate chain
`verify-full`	TLS only	no	chain and host name (or IP)

The default prefer encrypts when the server offers TLS, but does not check its certificate, and falls back to the unencrypted legacy port when TLS is not available. On a network you do not trust, use verify-ca or verify-full.

A rejected logon (wrong user or password) never falls back, and a certificate that fails verify-ca / verify-full is an error, not a reason to fall back. With allow, prefer and require, a successful TLS logon prints a one-time warning on standard error that the certificate was not verified; ARPETERADATA_NO_TLS_WARNING=1 silences it.

When sslca / sslcapath are not set, verify-ca and verify-full trust the system's CA certificates: OpenSSL's default locations, then the first distribution bundle found among /etc/pki/ca-trust/extracted/pem/tls-ca-bundle.pem, /etc/pki/tls/certs/ca-bundle.crt, /etc/ssl/certs/ca-certificates.crt, /etc/ssl/ca-bundle.pem and /etc/ssl/cert.pem. Setting SSL_CERT_FILE or SSL_CERT_DIR replaces that search. On Windows, the Windows ROOT certificate store is used instead.

Session

Option	Default	Meaning
`adbc.arpeteradata.charset`	`UTF8`	Session character set. Only `UTF8` (not case-sensitive) is accepted; any other value is rejected.
`adbc.arpeteradata.tmode`	server default (Teradata mode)	Transaction mode chosen at logon: `TERA` / `TERADATA` or `ANSI` (not case-sensitive). Any other value selects the server default. See Transactions.

The session time zone is always set to UTC right after logon (see Data types).

Timeouts

Option	Default	Meaning
`adbc.arpeteradata.login_timeout`	60 s (also when `0`)	Upper bound for each logon attempt; on expiry the connect fails with `Teradata logon timed out after N s`. With `prefer` and `allow`, the TLS attempt is capped at 5 s (or `login_timeout` if shorter) so the legacy port still gets its turn; the legacy-port logon keeps the full `login_timeout`.
`adbc.arpeteradata.query_timeout`	0 (no limit)	Socket read timeout, in seconds, for every call after logon. A server silent for longer fails the call with an I/O error and closes the connection: open a new one.

Even without a read timeout, a server or network that disappears without closing the connection is detected: the socket has TCP keepalive, so the call fails after about 2 minutes instead of blocking forever.

Result batching

Option	Default	Meaning
`adbc.arpeteradata.batch_size` (alias `adbc.arpeteradata.buffer_size`)	32000	Maximum rows per Arrow record batch. Set it on the database, or on a statement (the statement value wins). A zero, negative or non-numeric value is rejected. The integer option setters (`SetOptionInt`) are accepted too.

A batch also closes once it holds 256 MiB of row data (always at least one row), so very wide tables and LOB columns stay bounded in memory without tuning batch_size.

Ingest

Set on the statement. See Data types → Ingest and Compatibility → Bulk ingest. Since v0.3.2.

Option	Default	Meaning
`adbc.ingest.target_table`	—	Table to load; setting it makes `Execute` an ingest of the bound data. The driver quotes the name.
`adbc.ingest.target_db_schema`	the session's default database	Teradata database of the target table. Not allowed with `adbc.ingest.temporary`.
`adbc.ingest.mode`	`adbc.ingest.mode.create`	`adbc.ingest.mode.create` / `.append` / `.replace` / `.create_append`.
`adbc.ingest.temporary`	`false`	`true` loads into a volatile table.
`adbc.arpeteradata.ingest.varchar_length`	4000	Width `n` (1–32000) of the string columns the driver creates: `VARCHAR(n) CHARACTER SET UNICODE`; binary columns get `VARBYTE(2n)`, capped at 64000.
`adbc.ingest.target_catalog`	—	Teradata has no catalog level: a non-empty value fails with `NOT_IMPLEMENTED`.

Licence

Option	Meaning
`arpeio.adbc.license`	Licence blob, inline.
`arpeio.adbc.license_file`	Path to a `.lic` file.
`arpeio.adbc.license.status`	Read-only (`GetOption` on the database); reports `<state>;code=<ARROW_LIC_*>;tier=<tier>;expires=<epoch>`.

The driver also reads the shared ARPEIO_ADBC_LICENCE[_FILE] environment variables and an arpeio_adbc.lic file next to the library. Full resolution order in Licensing.

Standard ADBC connection options

Option	Values	Meaning
`adbc.connection.autocommit`	`true` (default) / `false`	Set on the connection, before or after it is opened. `false` starts an explicit transaction. Any other value is rejected (`INVALID_ARGUMENT`).
`adbc.connection.current_db_schema`	database name	Changes the session's default database after connecting (`DATABASE <name>`); an unknown name fails with `NOT_FOUND`.

Teradata has no catalogs, so there is no current-catalog setting.

Transactions

Teradata mode (TERA, the default). With autocommit off, the driver opens a transaction with BT; Commit sends ET and Rollback sends ABORT, and each opens the next transaction.
A failed request in Teradata mode rolls back the whole open transaction: the work since the last Commit is lost. Autocommit stays off, and the next statement starts a new transaction.
ANSI mode (ANSI). Commit sends COMMIT, Rollback sends ROLLBACK. ANSI never commits by itself, so with autocommit on the driver commits after each DML/DDL statement, and after a SELECT once its result stream is released.
With autocommit off, do not send BT, ET, ABORT, COMMIT or ROLLBACK as SQL: use the ADBC Commit and Rollback calls.
With autocommit on, a bound execute that goes out as several requests (more than 16000 rows or about 1 MB, or a stream of several batches) and a bulk ingest run in one transaction: all rows or none.
Commit and Rollback with autocommit on fail with INVALID_STATE.
Closing a connection rolls back its uncommitted work, then logs the session off. Commit before closing to keep the work.

Python

Python's dbapi.connect() turns autocommit off by default. For read-only work, pass autocommit=True, or call conn.commit() to keep what you wrote.

Cancelling a request

AdbcStatementCancel and AdbcConnectionCancel stop the request running on the connection, from any thread, on Linux and Windows.

A query still building its result fails with ADBC_STATUS_CANCELLED (SQLSTATE HY008, Teradata code 3110). A result being streamed ends at the next batch.
The connection stays usable: the next statement runs normally. A cancel with nothing running does nothing.
A bound execute sent as several requests is cancelled as a whole; with autocommit on, the requests already done are rolled back.
Cancel targets the connection's current request. Running a second statement on the same connection while a result is still open is not supported for cancel.
Releasing a result stream before reading it to the end cancels the rest of the request, so stopping early is cheap.

Parameterised queries

SELECT and DML statements with ? markers work through Prepare, Bind and Execute. For a SELECT, the bound rows must fit in one request (about 1 MB); a larger bind fails with NOT_IMPLEMENTED. GetParameterSchema reports each marker with the null type until parameters are bound, because Teradata does not describe parameter types. The accepted Arrow types are in Data types → Bound parameters.

Teradata accepts only CR as a line terminator: the driver rewrites LF and CRLF outside string literals and comments, so multi-line SQL works as written.

Legacy-port logon limits

These apply when the logon runs through TTU CLIv2 inside your process (see Authentication):

A logon that timed out, or a close whose logoff failed, keeps a CLIv2 session slot until all legacy-port connections of the process are closed. After about 300 such incidents, CLIv2 reports "no free session slots".
If your application already loaded the same CLIv2 library (for example through the Teradata ODBC driver), the driver shares it. CLIv2 is loaded once per process: a different ttu_path given later is ignored, with a one-time note on standard error.
Name lookups (DNS) for the server happen before the logon and are not bounded by login_timeout.

Environment variables

All are optional; a licence must come from somewhere (an option, a variable or a file next to the driver).

Variable	Effect
`ARPEIO_ADBC_LICENCE`	Licence blob, inline (note the British spelling).
`ARPEIO_ADBC_LICENCE_FILE`	Path to a licence `.lic` file.
`ARPEIO_ADBC_ALLOCATOR`	`mimalloc` (default) or `system`: the allocator for Arrow column buffers. Read once when the driver loads, so set it before your process loads the driver.
`ARPETERADATA_TTU_PATH`	Directory holding TTU CLIv2 (`libcliv2.so` / `wincli32.dll`) for the legacy-port logon, searched after the `ttu_path` option. No effect on the TLS logon.
`ARPETERADATA_GSSAPI_LIBRARY`	Linux: full path of the GSS-API library for the Kerberos logon over TLS. Default: `libgssapi_krb5.so.2` (MIT Kerberos), then `libgssapi_krb5.so`, then Heimdal's `libgssapi.so.3`, from the system library path. No effect on Windows (SSPI) or on the legacy port.
`ARPETERADATA_NO_TLS_WARNING`	`1` silences the once-per-process warning printed when a TLS logon runs without certificate verification.
`SSL_CERT_FILE` / `SSL_CERT_DIR`	Linux: replace the system CA search used by `verify-ca` / `verify-full` when `sslca` / `sslcapath` are not set.
`KRB5CCNAME` / `KRB5_CONFIG`	Kerberos ticket cache and `krb5.conf` location, read by the system Kerberos library.

Linux and Windows find TTU differently

Linux: TTU does not have to be installed. Set ttu_path (or ARPETERADATA_TTU_PATH) to the folder that holds libcliv2.so. A standard install under /opt/teradata/client is also found without it.
Windows: there is no DLL to copy. Install TTU with its installer and select CLIv2 (and TeraGSS) among the install options. The driver then finds it in the registry, with no option to set. Use ttu_path only for a copy outside a standard install.

See Where the driver looks for TTU.

Code is loaded from TTU directories

ttu_path and ARPETERADATA_TTU_PATH load code: the driver runs the CLIv2 library it finds there inside your process. Point them only at a directory that no other user can write to.

Not supported

LDAP over TLS without TTU: LDAP needs the legacy port (see Authentication → LDAP).
Partitioned execution (ExecutePartitions).

Three ways to connect​

URI​

Connection string​

Teradata cloud environments​

What you need​

Which port and sslmode​

Connect​

Check the connection​

Load, query and extract​

Option reference​

Target and credentials​

Logon mechanism​

Encryption / TLS​

Session​

Timeouts​

Result batching​

Ingest​

Licence​

Standard ADBC connection options​

Transactions​

Cancelling a request​

Parameterised queries​

Legacy-port logon limits​

Environment variables​

Not supported​

See also​