{"id":1743,"library":"teradatasql","title":"Teradata SQL Driver for Python","description":"teradatasql is the official Python driver for connecting to Teradata Vantage and other Teradata systems. It provides a DBAPI 2.0 compliant interface, allowing Python applications to connect to Teradata databases, execute SQL queries, and fetch results. The current stable version is 20.0.0.55. Teradata usually releases updates on an as-needed basis to support new features or address issues.","status":"active","version":"20.0.0.55","language":"en","source_language":"en","source_url":"https://github.com/Teradata/python-driver","tags":["database","SQL","Teradata","driver","DBAPI","data-warehousing"],"install":[{"cmd":"pip install teradatasql","lang":"bash","label":"Install stable version"}],"dependencies":[],"imports":[{"note":"The standard pattern is to import the module and call `teradatasql.connect()`.","wrong":"from teradatasql import connect # (less common, but not typical for direct imports)","symbol":"connect","correct":"import teradatasql\ncon = teradatasql.connect(...)"}],"quickstart":{"code":"import teradatasql\nimport os\n\n# --- Configuration (replace with your Teradata connection details) ---\n# It's recommended to use environment variables or a configuration management tool\nHOST = os.environ.get('TERADATA_HOST', 'your_teradata_host')\nUSER = os.environ.get('TERADATA_USER', 'your_username')\nPASSWORD = os.environ.get('TERADATA_PASSWORD', 'your_password')\nDATABASE = os.environ.get('TERADATA_DATABASE', 'your_database_name') # Optional\n\nif HOST == 'your_teradata_host':\n    print(\"Warning: Please configure TERADATA_HOST, TERADATA_USER, and TERADATA_PASSWORD environment variables or replace placeholders.\")\n    exit()\n\ncon = None\ncur = None\ntry:\n    # Connect to Teradata. For Teradata Vantage, the 'host' parameter is 'DBCName'.\n    # Additional parameters can be passed as keyword arguments or via a connection string.\n    # For instance, if you need a specific logon mechanism: logmech='TD2'\n    con = teradatasql.connect(host=HOST, user=USER, password=PASSWORD, database=DATABASE)\n    print(\"Successfully connected to Teradata.\")\n\n    cur = con.cursor()\n\n    # Example: Create a table (if it doesn't exist)\n    try:\n        cur.execute(\"CREATE TABLE my_test_table (id INTEGER, name VARCHAR(100));\")\n        print(\"Table 'my_test_table' created.\")\n    except teradatasql.OperationalError as e:\n        if \"already exists\" in str(e).lower():\n            print(\"Table 'my_test_table' already exists.\")\n        else:\n            raise # Re-raise other errors\n\n    # Example: Insert data\n    cur.execute(\"INSERT INTO my_test_table (id, name) VALUES (?, ?);\", (1, 'Alice'))\n    cur.execute(\"INSERT INTO my_test_table (id, name) VALUES (?, ?);\", (2, 'Bob'))\n    con.commit() # Commit the transaction as autocommit=False by default\n    print(\"Data inserted and committed.\")\n\n    # Example: Query data\n    cur.execute(\"SELECT id, name FROM my_test_table ORDER BY id;\")\n    print(\"\\nFetched data:\")\n    for row in cur.fetchall():\n        print(row)\n\n    # Example: Clean up (optional)\n    # cur.execute(\"DROP TABLE my_test_table;\")\n    # con.commit()\n    # print(\"Table 'my_test_table' dropped.\")\n\nexcept teradatasql.Error as e:\n    print(f\"Teradata SQL Error: {e}\")\n    if con:\n        con.rollback() # Rollback in case of error\nexcept Exception as e:\n    print(f\"An unexpected error occurred: {e}\")\nfinally:\n    if cur:\n        cur.close()\n        print(\"Cursor closed.\")\n    if con:\n        con.close()\n        print(\"Connection closed.\")","lang":"python","description":"This quickstart demonstrates how to establish a connection to a Teradata database, execute DDL and DML statements, commit changes, and query data using the `teradatasql` driver. It highlights the importance of using `os.environ.get` for sensitive credentials and proper resource management by closing cursors and connections. Note that `autocommit` is `False` by default, requiring explicit `con.commit()`."},"warnings":[{"fix":"Update your code to handle `Decimal` objects where appropriate. If you explicitly need `float` representation for older code, you might need to convert them manually (e.g., `float(decimal_value)`), though this is generally discouraged for precision-sensitive data.","message":"Starting with version 20.0.0.0, the driver now maps SQL `DECIMAL` types to Python's `Decimal` objects by default, instead of `float`. This change improves precision but may require updates to existing code that expects `float` values for decimal columns.","severity":"breaking","affected_versions":">=20.0.0.0"},{"fix":"Consult the `teradatasql` documentation for version 20.x to verify connection parameters and default settings. If encountering connection issues, explicitly specify parameters like `logmech` or review the new connection string format for complex configurations.","message":"Version 20.x introduced support for Teradata Vantage connection string formats and changed some default configuration settings. While traditional keyword arguments for `teradatasql.connect` are largely supported, existing code relying on specific parameter names or default behaviors (e.g., related to `logmech` or session settings) might need review.","severity":"breaking","affected_versions":">=20.0.0.0"},{"fix":"Always call `con.commit()` after executing statements that modify the database (DML or DDL). Use `con.rollback()` to undo changes in case of an error. Wrap database operations in `try...except...finally` blocks to ensure `commit()` or `rollback()` and `close()` are called.","message":"`teradatasql` defaults to `autocommit=False` (DBAPI 2.0 standard). This means `INSERT`, `UPDATE`, `DELETE`, and `DDL` statements will not be persisted to the database until `con.commit()` is explicitly called. Forgetting to commit will result in data not being saved.","severity":"gotcha","affected_versions":"All"},{"fix":"Always use `try...finally` blocks to ensure `cur.close()` and `con.close()` are called, even if errors occur during database operations. For simple scripts, a `with` statement for connection is not directly supported by `teradatasql`'s connect method, so explicit closing is necessary.","message":"It is crucial to close both the cursor (`cur.close()`) and the connection (`con.close()`) objects when you are finished with them. Failing to do so can lead to resource leaks on both the client and server sides, exhausting connection pools or consuming memory.","severity":"gotcha","affected_versions":"All"}],"env_vars":null,"last_verified":"2026-04-09T00:00:00.000Z","next_check":"2026-07-08T00:00:00.000Z"}