trino

library0.339.0pypypi✓ verified 26d ago

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.

database http-networking data

pip install trino

github ↗package ↗homepage ↗

INSTALL

IMPORT

SIG · TRINO

trino

databasepythonv0.339.0

Install

—

Import

—

Disk

—

Pass rate

0/ 10

Env Coverage0 / 10

glibc

3.9–3.13

musl

3.9–3.13

Install & Compatibility

Where this runs

tested against v0.339.0 · 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

musl

glibc

py 3.10

✕ build_error

2/3 runs

py 3.11

✕ build_error

2/3 runs

py 3.12

✕ build_error

2/3 runs

py 3.13

✕ build_error

2/3 runs

py 3.9

✕ build_error

2/3 runs

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

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

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.")

trino --version

Debug

Known issues

deprecatedPython 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.

affects: >=0.331.0

gotchaThe 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.

affects: >=0.336.0

gotchaWhen 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`.

affects: >=0.337.0

gotchaThe 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()`.

affects: *

gotchaWhen 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.

affects: *

gotchaVersion 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.

affects: >=0.334.0

breakingInstalling `trino[gssapi]` requires system-level Kerberos development libraries to be present (e.g., `libkrb5-dev` on Debian/Ubuntu, `krb5-devel` on RHEL/CentOS) for the `krb5` Python package to compile successfully. Without these, `pip install trino[gssapi]` will fail.

fix

Install the necessary system-level Kerberos development libraries (e.g., `sudo apt-get install libkrb5-dev` on Debian/Ubuntu, `sudo yum install krb5-devel` on RHEL/CentOS, or similar for other operating systems) before attempting to `pip install trino[gssapi]`.

affects: *

Errors

Common errors & fixes

ModuleNotFoundError: No module named 'trino'

The 'trino' Python package has not been installed in your current Python environment.

fix

pip install trino

trino.client.TrinoConnectionError: Failed to connect: HTTPSConnectionPool(host='your_host', port=8080): Max retries exceeded with url: /v1/statement (Caused by NewConnectionError('<urllib3.connection.HTTPSConnection object at 0x...>: Failed to establish a new connection: [Errno 111] Connection refused'))

The Trino server is either not running, not accessible from the client's machine, or the specified host and port are incorrect.

fix

Verify that the Trino server is running, check network connectivity and firewall rules, and confirm the `host` and `port` parameters in your connection string.

sqlalchemy.exc.NoSuchModuleError: Can't load plugin: sqlalchemy.dialects:trino

The optional SQLAlchemy adapter for the Trino client was not installed.

fix

pip install trino[sqlalchemy]

trino.client.TrinoConnectionError: Failed to connect: HTTPSConnectionPool(host='your_host', port=8443): Max retries exceeded with url: /v1/statement (Caused by SSLError(SSLCertVerificationError(1, '[SSL: CERTIFICATE_VERIFY_FAILED] certificate verify failed: self signed certificate in certificate chain')))

The Trino server is using an SSL certificate that is not trusted by the client's system, often a self-signed certificate or one issued by an unknown Certificate Authority (CA).

fix

Provide the path to the trusted CA certificate using the `verify` parameter (e.g., `trino.dbapi.connect(..., verify='/path/to/ca.crt')`) or, for development/testing, set `verify=False` to disable SSL verification.

Upgrade

Version history

0.339.0latest on PyPI · released Aug 20, 2026

Audit

Dependencies

requestsrequiredCore HTTP communication, regularly updated for security patches.

orjsonoptionalUsed for faster JSON serialization/deserialization, migrated to from built-in `json` in 0.336.0. Recommended for performance.

lz4optionalOptional dependency for spooling protocol compression (json+lz4). Client gracefully handles its absence.

zstandardoptionalOptional dependency for spooling protocol compression (json+zstd). Client gracefully handles its absence.

requests-gssapioptionalRequired for GSSAPI/Kerberos authentication, installed with `trino[gssapi]`.

Agent activity

44 hits · last 30 days

node

OpenAI (training)

Resources

githubhttps://github.com/trinodb/trino-python-client ↗

packagehttps://pypi.org/project/trino/ ↗

homepagehttps://trino.io ↗