Trino Python Client

By default, the client operates in autocommit mode. To use transactions, set the isolation_level parameter to a value other than IsolationLevel.AUTOCOMMIT (e.g., IsolationLevel.REPEATABLE_READ).

When using a with context manager:

1. The transaction starts when the first SQL statement is executed.
2. trino.dbapi.Connection.commit() is called automatically if the block exits successfully.
3. trino.dbapi.Connection.rollback() is called if an exception occurs.

from trino.dbapi import connect
from trino.transaction import IsolationLevel

with connect(
        isolation_level=IsolationLevel.REPEATABLE_READ,
        ...
) as conn:
    cur = conn.cursor()
    cur.execute('INSERT INTO sometable VALUES (1, 2, 3)')
    cur.fetchall()
    cur.execute('INSERT INTO sometable VALUES (4, 5, 6)')
    cur.fetchall()

User Impersonation

If the user submitting the query is different from the authenticated user, set user to the target username. The principal_id is automatically extracted from the auth object (e.g., username in BasicAuth, sub in JWT, or service-name in Kerberos). Ensure the principal_id has permission to impersonate the user in Trino.

Extra Credentials

You can send extra credentials as a list of tuples to trino.dbapi.connect using the extra_credential parameter.

import trino
conn = trino.dbapi.connect(
    host='localhost',
    port=443,
    user='the-user',
    extra_credential=[('a.username', 'bar'), ('a.password', 'foo')],
)

cur = conn.cursor()
cur.execute('SELECT * FROM system.runtime.nodes')
rows = cur.fetchall()

The trino.dbapi.connect function provides a standard Python DBAPI 2.0 implementation. If the host provided is a valid URL, the port and http_schema will be automatically determined (e.g., https://my-trino-server:9999 sets http_schema to https and port to 9999).

To control how many rows are fetched at once, adjust trino.dbapi.Cursor.arraysize. By default, Cursor.fetchmany() fetches one row.

from trino.dbapi import connect

conn = connect(
    host="<host>",
    port=<port>,
    user="<username>",
    catalog="<catalog>",
    schema="<schema>",
)
cur = conn.cursor()
cur.execute("SELECT * FROM system.runtime.nodes")
rows = cur.fetchall()

To use the low-level DBAPI 2.0 interface, install the base package:

$ pip install trino

To use the SQLAlchemy adapter, install the package with the sqlalchemy extra:

$ pip install trino[sqlalchemy]

The Trino Spooling protocol breaks query results into segments. The client handles two types of segments via the SegmentType enum:

• inline: Data is base64 encoded and included directly in the response. Use InlineSegment to access this.
• spooled: Data is stored remotely (e.g., S3). The client must fetch the data via a URI and optionally acknowledge processing. Use SpooledSegment to handle these.

Segments provide access to metadata (containing uncompressedSize and segmentSize) and the data itself.

For Kerberos authentication, install the extra: pip install trino[kerberos]. Use trino.auth.KerberosAuthentication.

For GSSAPI authentication, install the extra: pip install trino[gssapi]. Use trino.auth.GSSAPIAuthentication. GSSAPI uses requests-gssapi under the hood.

Both support DBAPI and SQLAlchemy via the auth parameter in connect() or connect_args.

# Kerberos DBAPI Example
from trino.dbapi import connect
from trino.auth import KerberosAuthentication

conn = connect(
    user="<username>",
    auth=KerberosAuthentication(...),
    http_scheme="https",
    ...
)

# GSSAPI SQLAlchemy Example
from sqlalchemy import create_engine
from trino.auth import GSSAPIAuthentication

engine = create_engine(
    "trino://<username>@<host>:<port>/<catalog>",
    connect_args={
        "auth": GSSAPIAuthentication(...),
        "http_scheme": "https",
    }
)

Use trino.auth.BasicAuthentication for clusters configured with Password file, LDAP, or Salesforce authentication.

DBAPI: Pass the auth object to connect(). SQLAlchemy: Include credentials in the connection string or pass the auth object via connect_args.

# DBAPI
from trino.dbapi import connect
from trino.auth import BasicAuthentication

conn = connect(
    user="<username>",
    auth=BasicAuthentication("<username>", "<password>"),
    http_scheme="https",
    ...
)

# SQLAlchemy
from sqlalchemy import create_engine

engine = create_engine("trino://<username>:<password>@<host>:<port>/<catalog>")
# OR via connect_args
from trino.auth import BasicAuthentication
engine = create_engine(
    "trino://<username>@<host>:<port>/<catalog>",
    connect_args={
        "auth": BasicAuthentication("<username>", "<password>"),
        "http_scheme": "https",
    }
)

You can specify authorization roles for different catalogs using the roles parameter in trino.dbapi.connect().

• To set specific roles for specific catalogs, pass a dictionary where keys are catalog names and values are the roles: {"catalog1": "roleA", "catalog2": "roleB"}.
• To set a single role for the system catalog, pass a string: roles="role1" (equivalent to {"system": "role1"}).

import trino

# Specific roles per catalog
conn = trino.dbapi.connect(
    host='localhost',
    port=443,
    user='the-user',
    roles={"catalog1": "roleA", "catalog2": "roleB"},
)

# Single role for the system catalog
conn = trino.dbapi.connect(
    host='localhost',
    port=443,
    user='the-user',
    roles="role1"
)