{"id":2309,"library":"teradatasqlalchemy","title":"Teradata SQL Dialect for SQLAlchemy","description":"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.","status":"active","version":"20.0.0.9","language":"en","source_language":"en","source_url":"https://github.com/Teradata/sqlalchemy-teradata","tags":["sqlalchemy","database","teradata","dialect","data-access"],"install":[{"cmd":"pip install teradatasqlalchemy","lang":"bash","label":"Install latest version"}],"dependencies":[{"reason":"teradatasqlalchemy 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.","package":"SQLAlchemy"},{"reason":"The 'teradatasql' dialect, used by teradatasqlalchemy, relies on the teradatasql driver for connecting to Teradata without requiring ODBC.","package":"teradatasql"}],"imports":[{"note":"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.","symbol":"create_engine","correct":"from sqlalchemy import create_engine"}],"quickstart":{"code":"import os\nfrom sqlalchemy import create_engine, text\n\n# Get connection details from environment variables for security and flexibility\ntd_host = os.environ.get(\"TD_HOST\", \"your_teradata_host\")\ntd_user = os.environ.get(\"TD_USER\", \"your_username\")\ntd_password = os.environ.get(\"TD_PASSWORD\", \"your_password\")\ntd_database = os.environ.get(\"TD_DATABASE\", \"your_database\") # Optional, can be empty\n\n# Construct the connection string using the 'teradatasql' dialect\n# This dialect (teradatasql://) does NOT require an ODBC driver.\n# If td_database is provided, include it in the connection string.\nif td_database:\n    connection_string = f\"teradatasql://{td_user}:{td_password}@{td_host}/?database={td_database}\"\nelse:\n    connection_string = f\"teradatasql://{td_user}:{td_password}@{td_host}\"\n\nprint(f\"Attempting to connect to Teradata at {td_host}...\")\n\ntry:\n    # Create the SQLAlchemy engine\n    engine = create_engine(connection_string)\n\n    # Establish a connection and execute a simple query\n    with engine.connect() as connection:\n        # Example: Execute a simple SELECT 1 query to verify connection\n        result = connection.execute(text(\"SELECT 1 AS test_column\")).scalar()\n        print(f\"Connection successful! Query result: {result}\")\n\n        # Example: Execute a query to fetch data from a table\n        # Make sure 'your_table' and 'your_column' exist in your Teradata database\n        # try:\n        #     sample_data = connection.execute(text(\"SELECT TOP 5 column1 FROM your_table\")).fetchall()\n        #     print(\"Sample data:\", sample_data)\n        # except Exception as query_e:\n        #     print(f\"Error executing sample query: {query_e}\")\n\nexcept Exception as e:\n    print(f\"Error connecting to Teradata: {e}\")\n    print(\"Please ensure environment variables (TD_HOST, TD_USER, TD_PASSWORD, TD_DATABASE) are set correctly \")\n    print(\"and network connectivity to the Teradata host on port 1025 (default) is available.\")\n","lang":"python","description":"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."},"warnings":[{"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.","message":"Older 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.","severity":"breaking","affected_versions":"<17.20.0.0"},{"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.","message":"There 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.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Ensure your Python environment is a 64-bit installation compatible with Python 3.4+.","message":"The `teradatasqlalchemy` library requires 64-bit Python 3.4 or later. 32-bit Python installations are explicitly not supported and will lead to errors.","severity":"gotcha","affected_versions":"All versions"},{"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.","message":"Incorrect 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.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Use the `--no-cache-dir` option with `pip install` to force the download of the new version: `pip install --no-cache-dir teradatasqlalchemy`.","message":"When 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.","severity":"gotcha","affected_versions":"All versions"}],"env_vars":null,"last_verified":"2026-04-09T00:00:00.000Z","next_check":"2026-07-08T00:00:00.000Z"}