Trino Python Client

Warnings

• deprecated 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).
  Fix: Upgrade your Python environment to 3.9 or newer.
• gotcha 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.
  Fix: For optimal performance, explicitly `pip install orjson`. Review any custom JSON serialization/deserialization logic if unexpected behavior arises.
• gotcha 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.
  Fix: If using spooling with compression, ensure the necessary libraries are installed, e.g., `pip install trino[full]` or `pip install lz4 zstandard`.
• gotcha 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.
  Fix: Set `cursor.arraysize = N` (where `N` is your desired batch size) before calling `fetchmany()` to retrieve multiple rows at once, or use `fetchall()`.
• gotcha 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.
  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.
• gotcha 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.
  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.

Install

• pip install trino Standard installation
• pip install trino[gssapi] With GSSAPI/Kerberos support
• pip install trino[full] Full installation with optional dependencies

Imports

• connect

  from trino.dbapi import connect

  Standard DBAPI 2.0 connection
• trino

  import trino

  Alternative for accessing the dbapi.connect function via 'trino.dbapi.connect'
• BasicAuthentication

  from trino.auth import BasicAuthentication

  For connecting to LDAP-configured Trino clusters

Quickstart

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.

import os
from trino.dbapi import connect
from trino.auth import BasicAuthentication

TRINO_HOST = os.environ.get('TRINO_HOST', 'localhost')
TRINO_PORT = int(os.environ.get('TRINO_PORT', '8080'))
TRINO_USER = os.environ.get('TRINO_USER', 'your_user')
TRINO_CATALOG = os.environ.get('TRINO_CATALOG', 'system')
TRINO_SCHEMA = os.environ.get('TRINO_SCHEMA', 'runtime')
TRINO_PASSWORD = os.environ.get('TRINO_PASSWORD') # Optional, for BasicAuth
TRINO_HTTP_SCHEME = os.environ.get('TRINO_HTTP_SCHEME', 'http')


auth = None
if TRINO_PASSWORD:
    auth = BasicAuthentication(TRINO_USER, TRINO_PASSWORD)

try:
    with connect(
        host=TRINO_HOST,
        port=TRINO_PORT,
        user=TRINO_USER,
        catalog=TRINO_CATALOG,
        schema=TRINO_SCHEMA,
        http_scheme=TRINO_HTTP_SCHEME,
        auth=auth # Pass auth if not None
    ) as conn:
        with conn.cursor() as cur:
            cur.execute('SELECT node_id, state FROM system.runtime.nodes')
            rows = cur.fetchall()
            for row in rows:
                print(row)
except Exception as e:
    print(f"An error occurred: {e}")
    print("Please ensure a Trino server is running and accessible at the specified host and port.")
    print("For secure connections, ensure 'TRINO_HTTP_SCHEME' is 'https' and provide authentication details.")