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
muslpy 3.10–3.95 runs
installs and imports cleanly · install 0.0s · import 0.748s · 389.6MB
glibcpy 3.10–3.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.")
Errors
Common errors & fixes
ModuleNotFoundError: No module named 'teradatasql'
The underlying Teradata DBAPI driver (`teradatasql`) is not installed, which `teradatasqlalchemy` depends on.
fixInstall 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.
fixVerify 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.
fixUpdate `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.
fixEnsure `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.