Registry / database / teradatasqlalchemy

teradatasqlalchemy

JSON →
library20.0.0.9pypypi✓ verified 26d ago

teradatasqlalchemy provides a SQL dialect for SQLAlchemy, enabling Python applications to connect to and interact with the Teradata Database. It offers an abstraction layer over the Teradata DBAPI, allowing users to leverage SQLAlchemy's ORM or Core features. The library supports 64-bit Python 3.4 and later. The current version is 20.0.0.9, released on December 15, 2025, with frequent updates to support new Teradata datatypes and features.

pip install teradatasqlalchemy
INSTALL
IMPORT
SIG · TERADATASQLALCHEMY
T
teradatasqlalchemy
databasepythonv20.0.0.9
Install
6.8s avg
Import
694ms
Disk
389MB
Pass rate
10/ 10
Env Coverage10 / 10
glibc
3.93.13
musl
3.93.13
Install & Compatibility
Where this runs
tested against v20.0.0.9 · pip install
no network on importno background threads
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
musl
py 3.103.95 runs
installs and imports cleanly · install 0.0s · import 0.748s · 389.6MB
glibc
py 3.103.95 runs
installs and imports cleanly · install 6.8s · import 0.640s · 388MB
389MB installed
● package 389MB
Code
Verified usage

Verified import paths — ran on the pinned version, not inferred.

create_engine
from sqlalchemy import create_engine
The dialect is automatically registered and instantiated when 'teradatasql://' is used in the connection string, so explicit import of a dialect class is typically not needed.

This quickstart demonstrates how to establish a connection to a Teradata database using teradatasqlalchemy and SQLAlchemy's `create_engine` function. It uses environment variables for secure credential management and executes a basic query to verify the connection. The `teradatasql://` dialect is recommended for direct connections without ODBC.

import os from sqlalchemy import create_engine, text # Get connection details from environment variables for security and flexibility td_host = os.environ.get("TD_HOST", "your_teradata_host") td_user = os.environ.get("TD_USER", "your_username") td_password = os.environ.get("TD_PASSWORD", "your_password") td_database = os.environ.get("TD_DATABASE", "your_database") # Optional, can be empty # Construct the connection string using the 'teradatasql' dialect # This dialect (teradatasql://) does NOT require an ODBC driver. # If td_database is provided, include it in the connection string. if td_database: connection_string = f"teradatasql://{td_user}:{td_password}@{td_host}/?database={td_database}" else: connection_string = f"teradatasql://{td_user}:{td_password}@{td_host}" print(f"Attempting to connect to Teradata at {td_host}...") try: # Create the SQLAlchemy engine engine = create_engine(connection_string) # Establish a connection and execute a simple query with engine.connect() as connection: # Example: Execute a simple SELECT 1 query to verify connection result = connection.execute(text("SELECT 1 AS test_column")).scalar() print(f"Connection successful! Query result: {result}") # Example: Execute a query to fetch data from a table # Make sure 'your_table' and 'your_column' exist in your Teradata database # try: # sample_data = connection.execute(text("SELECT TOP 5 column1 FROM your_table")).fetchall() # print("Sample data:", sample_data) # except Exception as query_e: # print(f"Error executing sample query: {query_e}") except Exception as e: print(f"Error connecting to Teradata: {e}") print("Please ensure environment variables (TD_HOST, TD_USER, TD_PASSWORD, TD_DATABASE) are set correctly ") print("and network connectivity to the Teradata host on port 1025 (default) is available.")
Debug
Known issues
breakingOlder versions of `teradatasqlalchemy` (prior to `17.20.0.0`) are not compatible with SQLAlchemy 2.0 or newer. Attempting to use them together will result in errors.
fix
Upgrade `teradatasqlalchemy` to version `17.20.0.0` or higher to ensure compatibility with SQLAlchemy 2.0+. If upgrading is not feasible, downgrade SQLAlchemy to a 1.x version.
affects: <17.20.0.0
gotchaThere are two main SQLAlchemy dialects for Teradata: `teradatasqlalchemy` (uses `teradatasql://` in connection string) and the older `sqlalchemy-teradata` (uses `teradata://`). `teradatasqlalchemy` is the recommended package for new development as it directly integrates with the `teradatasql` driver and does NOT require a separate ODBC driver installation. The `sqlalchemy-teradata` dialect, which depends on an ODBC driver, is less actively maintained and can lead to connection issues if ODBC is not correctly configured.
fix
For new projects, always use `teradatasqlalchemy` with the `teradatasql://` connection prefix. If you encounter connection issues, verify which dialect you are attempting to use and ensure the correct underlying driver/ODBC setup is in place for that dialect.
affects: All versions
gotchaThe `teradatasqlalchemy` library requires 64-bit Python 3.4 or later. 32-bit Python installations are explicitly not supported and will lead to errors.
fix
Ensure your Python environment is a 64-bit installation compatible with Python 3.4+.
affects: All versions
gotchaIncorrect or unescaped connection string parameters are a common source of connection failures. Special characters in `user`, `password`, `database`, or `host` components of the URL should be URL-encoded.
fix
Carefully construct your connection string, verifying `host`, `user`, `password`, `database`, and `port` (default 1025). URL encode any special characters within these parameters using `urllib.parse.quote_plus` for robust connections.
affects: All versions
gotchaWhen upgrading `teradatasqlalchemy` to a new version, `pip` might use a cached older version, preventing the update. This can lead to unexpected behavior or an inability to access new features/fixes.
fix
Use the `--no-cache-dir` option with `pip install` to force the download of the new version: `pip install --no-cache-dir teradatasqlalchemy`.
affects: All versions
Errors
Common errors & fixes
ModuleNotFoundError: No module named 'teradatasql'
The underlying Teradata DBAPI driver (`teradatasql`) is not installed, which `teradatasqlalchemy` depends on.
fix
Install the `teradatasql` driver: `pip install teradatasql`
sqlalchemy.exc.OperationalError: (teradatasql.Error) (-21010, '[HY000] [Teradata][socket] (21010) Could not resolve Teradata server name: {your_server_name}.')
The hostname provided in the connection string could not be resolved to an IP address, or the server is unreachable.
fix
Verify the `host` parameter in your SQLAlchemy connection string for typos, ensure the Teradata server hostname is correct, and check network connectivity from your machine to the Teradata server.
sqlalchemy.exc.ProgrammingError: (teradatasql.Error) (-9999, 'Unknown Teradata data type: {some_type_name}')
`teradatasqlalchemy` (or the underlying `teradatasql` driver) does not recognize or support a specific Teradata data type encountered during schema reflection or query execution.
fix
Update `teradatasqlalchemy` and `teradatasql` to their latest versions. If the issue persists, consider mapping the unsupported type to a generic SQLAlchemy type like `String` in your model or during reflection.
sqlalchemy.exc.NoSuchModuleError: Can't load plugin: sqlalchemy.dialects:teradata
The specified dialect name in the connection string is incorrect, or the `teradatasqlalchemy` library is not properly installed or registered with SQLAlchemy.
fix
Ensure `teradatasqlalchemy` is installed (`pip install teradatasqlalchemy`) and use the correct dialect name `teradatasqlalchemy` in your connection string: `create_engine('teradatasqlalchemy://user:pass@host:port/database')`.
Upgrade
Version history
20.0.0.9latest on PyPI · released Dec 16, 2025
Audit
Dependencies
SQLAlchemyrequiredteradatasqlalchemy is a dialect for SQLAlchemy, requiring it as a core dependency. Compatibility with SQLAlchemy 2.0+ was added in teradatasqlalchemy version 17.20.0.0.
teradatasqlrequiredThe 'teradatasql' dialect, used by teradatasqlalchemy, relies on the teradatasql driver for connecting to Teradata without requiring ODBC.
Agent activity
19 hits · last 30 days
node
14
Meta
1
Amazon
1
OpenAI (training)
1
Resources
teradatasqlalchemy — pip install teradatasqlalchemy · libregistry