{"library":"trino","title":"Trino Python Client","description":"The `trino` Python client provides a client interface to query Trino, a distributed SQL engine for interactive and batch big data processing. It offers a low-level client, a DBAPI 2.0 implementation, and a SQLAlchemy adapter. The current version is 0.337.0 and releases are frequent, often several per month, incorporating fixes, features, and dependency updates.","status":"active","version":"0.337.0","language":"en","source_language":"en","source_url":"https://github.com/trinodb/trino-python-client","tags":["database","sql","trino","dbapi","etl","big data"],"install":[{"cmd":"pip install trino","lang":"bash","label":"Standard installation"},{"cmd":"pip install trino[gssapi]","lang":"bash","label":"With GSSAPI/Kerberos support"},{"cmd":"pip install trino[full]","lang":"bash","label":"Full installation with optional dependencies"}],"dependencies":[{"reason":"Core HTTP communication, regularly updated for security patches.","package":"requests","optional":false},{"reason":"Used for faster JSON serialization/deserialization, migrated to from built-in `json` in 0.336.0. Recommended for performance.","package":"orjson","optional":true},{"reason":"Optional dependency for spooling protocol compression (json+lz4). Client gracefully handles its absence.","package":"lz4","optional":true},{"reason":"Optional dependency for spooling protocol compression (json+zstd). Client gracefully handles its absence.","package":"zstandard","optional":true},{"reason":"Required for GSSAPI/Kerberos authentication, installed with `trino[gssapi]`.","package":"requests-gssapi","optional":true}],"imports":[{"note":"Standard DBAPI 2.0 connection","symbol":"connect","correct":"from trino.dbapi import connect"},{"note":"Alternative for accessing the dbapi.connect function via 'trino.dbapi.connect'","symbol":"trino","correct":"import trino"},{"note":"For connecting to LDAP-configured Trino clusters","symbol":"BasicAuthentication","correct":"from trino.auth import BasicAuthentication"}],"quickstart":{"code":"import os\nfrom trino.dbapi import connect\nfrom trino.auth import BasicAuthentication\n\nTRINO_HOST = os.environ.get('TRINO_HOST', 'localhost')\nTRINO_PORT = int(os.environ.get('TRINO_PORT', '8080'))\nTRINO_USER = os.environ.get('TRINO_USER', 'your_user')\nTRINO_CATALOG = os.environ.get('TRINO_CATALOG', 'system')\nTRINO_SCHEMA = os.environ.get('TRINO_SCHEMA', 'runtime')\nTRINO_PASSWORD = os.environ.get('TRINO_PASSWORD') # Optional, for BasicAuth\nTRINO_HTTP_SCHEME = os.environ.get('TRINO_HTTP_SCHEME', 'http')\n\n\nauth = None\nif TRINO_PASSWORD:\n    auth = BasicAuthentication(TRINO_USER, TRINO_PASSWORD)\n\ntry:\n    with connect(\n        host=TRINO_HOST,\n        port=TRINO_PORT,\n        user=TRINO_USER,\n        catalog=TRINO_CATALOG,\n        schema=TRINO_SCHEMA,\n        http_scheme=TRINO_HTTP_SCHEME,\n        auth=auth # Pass auth if not None\n    ) as conn:\n        with conn.cursor() as cur:\n            cur.execute('SELECT node_id, state FROM system.runtime.nodes')\n            rows = cur.fetchall()\n            for row in rows:\n                print(row)\nexcept Exception as e:\n    print(f\"An error occurred: {e}\")\n    print(\"Please ensure a Trino server is running and accessible at the specified host and port.\")\n    print(\"For secure connections, ensure 'TRINO_HTTP_SCHEME' is 'https' and provide authentication details.\")","lang":"python","description":"This quickstart demonstrates how to connect to a Trino server using the DBAPI interface, execute a simple query, and fetch results. It uses environment variables for connection parameters for flexibility and basic authentication if a password is provided. The `with` statement ensures proper resource management for both connection and cursor."},"warnings":[{"fix":"Upgrade your Python environment to 3.9 or newer.","message":"Python 3.8 support has been dropped as of version 0.331.0. Users on Python 3.8 or older must upgrade their Python environment to a supported version (Python >= 3.9).","severity":"deprecated","affected_versions":">=0.331.0"},{"fix":"For optimal performance, explicitly `pip install orjson`. Review any custom JSON serialization/deserialization logic if unexpected behavior arises.","message":"The client migrated from the built-in `json` module to `orjson` in version 0.336.0 for performance. While largely compatible, applications with strict dependencies on specific `json` module behaviors or those not installing `orjson` as an optional dependency might see subtle behavioral differences or reduced performance if `orjson` isn't available.","severity":"gotcha","affected_versions":">=0.336.0"},{"fix":"If using spooling with compression, ensure the necessary libraries are installed, e.g., `pip install trino[full]` or `pip install lz4 zstandard`.","message":"When using the client's spooling protocol with compression (e.g., `json+lz4`, `json+zstd`), the corresponding compression libraries (`lz4`, `zstandard`) must be installed. As of 0.337.0, the client gracefully handles their absence by disabling compression, which can lead to unexpected performance or larger data transfer if compression was intended.","severity":"gotcha","affected_versions":">=0.337.0"},{"fix":"Set `cursor.arraysize = N` (where `N` is your desired batch size) before calling `fetchmany()` to retrieve multiple rows at once, or use `fetchall()`.","message":"The default `Cursor.arraysize` is 1, meaning `fetchmany()` will only return one row by default. This can be inefficient for fetching multiple rows in a loop.","severity":"gotcha","affected_versions":"*"},{"fix":"Remove trailing semicolons from individual SQL statements when passing them to `cursor.execute()`, especially if concatenating multiple statements or running them one by one.","message":"When executing multiple SQL statements in a single `cursor.execute()` call, ensure that individual statements are *not* terminated with a semicolon ';'. The Python client often 'freaks out' or misinterprets queries with trailing semicolons.","severity":"gotcha","affected_versions":"*"},{"fix":"Always use `http_scheme='https'` and configure proper SSL/TLS verification in production environments. Only enable insecure channels with extreme caution and understanding of the security implications.","message":"Version 0.334.0 introduced the ability to 'Allow authentication over insecure channel'. While this can be useful for specific test environments, using it in production without proper TLS (i.e., `http_scheme='https'` and certificate verification) is a significant security risk.","severity":"gotcha","affected_versions":">=0.334.0"}],"env_vars":null,"last_verified":"2026-04-06T00:00:00.000Z","next_check":"2026-07-05T00:00:00.000Z"}