Skip to content
Open
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
33 changes: 33 additions & 0 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -54,6 +54,39 @@ rows for example `Cursor.fetchone()` or `Cursor.fetchmany()`. By default
`Cursor.fetchmany()` fetches one row. Please set
`trino.dbapi.Cursor.arraysize` accordingly.

**Connection parameters**

`trino.dbapi.connect()` accepts the same arguments as `trino.dbapi.Connection`.
All parameters are optional except `host`. A parameter left as `None` means
"not set" (its server-side default applies), except where noted below.

| Parameter | Type | Default | Description |
| :--- | :--- | :--- | :--- |
| `host` | `str` | — | The hostname or IP address of the Trino coordinator. May be a URL; a scheme and port in the URL take precedence over `http_scheme` and `port`. |
| `port` | `int` | `443` for https, `8080` for http | The port number of the Trino coordinator. |
| `user` | `str` | `None` | The username for the session, sent as the `X-Trino-User` header. |
| `source` | `str` | `'trino-python-client'` | The client name shown for queries in the Trino Web UI. |
| `catalog` | `str` | `None` | The default catalog to use for queries. |
| `schema` | `str` | `None` | The default schema to use for queries. |
| `session_properties` | `dict` | `None` | A dictionary of session properties, e.g. `{'query_max_run_time': '10m'}`. |
| `http_headers` | `dict` | `None` | A dictionary of additional custom HTTP headers to send with requests. |
| `http_scheme` | `str` | auto-detected | Protocol to use: `'http'` or `'https'`. Resolved from the host URL scheme when present, otherwise from this argument, otherwise from the port (`443` → `'https'`, `8080` → `'http'`), defaulting to `'http'`. |
| `auth` | `object` | `None` | An authentication instance, e.g. `BasicAuthentication`, `JWTAuthentication` or `KerberosAuthentication`. `None` means no authentication. |
| `extra_credential` | `list` of `(name, value)` tuples | `None` | Extra credentials sent as `X-Trino-Extra-Credential` headers. |
| `max_attempts` | `int` | `3` | Maximum number of attempts for each HTTP request, including retries. |
| `request_timeout` | `float` | `30.0` | Client-side timeout (in seconds) for each HTTP request. |
| `isolation_level` | `trino.transaction.IsolationLevel` | `IsolationLevel.AUTOCOMMIT` | Transaction isolation level. |
| `verify` | `bool` \| `str` | `True` | Controls TLS certificate verification. Set to `False` to disable, or provide a path to a CA bundle. |
| `http_session` | `requests.Session` | `None` | A custom HTTP session. `None` creates a new default session. |
| `client_tags` | `list[str]` | `None` | A list of tags sent as the `X-Trino-Client-Tags` header. |
| `legacy_primitive_types` | `bool` | `False` | When `True`, query results are not converted to the corresponding Python types. |
| `legacy_prepared_statements` | `bool` | auto-detected | Force the use (`True`) or not (`False`) of legacy prepared statements. When not given, the client probes the coordinator once per host and port and caches the result. |
| `roles` | `dict[str, str]` \| `str` | `None` | Authorization roles: a dict mapping catalog names to roles, or a single string used as the role for the `system` catalog. |
| `timezone` | `str` | client's local time zone | The time zone for the session, e.g. `'US/Pacific'`. |
| `encoding` | `str` \| `list[str]` | all supported encodings | Spooled protocol encodings in order of preference, e.g. `'json+zstd'` or `['json+zstd', 'json']`. |
| `heartbeat_interval` | `float` | `30.0` | Interval in seconds between heartbeat requests for long-running queries. |
| `allow_insecure_auth` | `bool` | `False` | Allow authentication over plain `http`. The coordinator must also be configured with `http-server.authentication.allow-insecure-over-http=true`. |

**Monitoring query progress**

Since queries can take a while to complete, it is useful to be able to monitor
Expand Down
62 changes: 62 additions & 0 deletions trino/dbapi.py
Original file line number Diff line number Diff line change
Expand Up @@ -139,6 +139,68 @@ class Connection:
statement, can also be cancelled. Transactions are not supported by this
client implementation yet.

:param host: the hostname or IP address of the Trino coordinator. It may
be a plain hostname or a URL; a scheme and port given in the
URL take precedence over the ``http_scheme`` and ``port``
arguments.
:param port: the coordinator port. Defaults to 443 for ``https`` and
8080 for ``http`` once ``http_scheme`` is resolved.
:param user: the session user, sent as the ``X-Trino-User`` header.
:param source: the client name shown for queries in the Trino Web UI.
Defaults to ``"trino-python-client"``.
:param catalog: the default catalog used by SQL statements.
:param schema: the default schema used by SQL statements.
:param session_properties: a dict of session properties for the session,
e.g. ``{'query_max_run_time': '10m'}``.
:param http_headers: additional HTTP headers sent with each request.
:param http_scheme: ``"http"`` or ``"https"``. Resolved from the host URL
scheme when present, otherwise from this argument,
otherwise from the port (443 maps to ``https``,
8080 maps to ``http``), defaulting to ``"http"``.
:param auth: an authentication instance (e.g. ``BasicAuthentication``,
``JWTAuthentication``); ``None`` means no authentication.
Authentication requires TLS unless ``allow_insecure_auth``
is set.
:param extra_credential: extra credentials as a list of
``(name, value)`` tuples, sent as
``X-Trino-Extra-Credential`` headers.
:param max_attempts: maximum attempts for each HTTP request, including
retries. Defaults to 3.
:param request_timeout: client-side timeout in seconds for each HTTP
request. Defaults to 30.0.
:param isolation_level: the transaction isolation level, one of
``trino.transaction.IsolationLevel``. Defaults to
``IsolationLevel.AUTOCOMMIT``.
:param verify: controls TLS certificate verification. ``True`` (default)
verifies against the system CA bundle, ``False`` disables
verification, and a string is treated as the path to a CA
bundle.
:param http_session: a custom ``requests.Session`` to use for HTTP;
a new default session is created when not given.
:param client_tags: a list of tags sent as the ``X-Trino-Client-Tags``
header.
:param legacy_primitive_types: when ``True``, query results are not
converted to the corresponding Python
types. See "Legacy Primitive types" below.
:param legacy_prepared_statements: forces the use (``True``) or not
(``False``) of legacy prepared
statements. When not given, the client
probes the coordinator once per
host and port and caches the result.
:param roles: authorization roles as a dict mapping catalog names to
roles, or a single string which is used as the role for
the ``system`` catalog.
:param timezone: the session time zone, e.g. ``"US/Pacific"``. When not
given, the client's local time zone is used.
:param encoding: the spooling protocol encodings in order of preference,
e.g. ``"json+zstd"`` or ``["json+zstd", "json"]``.
Defaults to every encoding supported by the installed
codecs. See "Spooled protocol" below.
:param heartbeat_interval: interval in seconds between heartbeat requests
for long-running queries. Defaults to 30.0.
:param allow_insecure_auth: allows authentication over plain ``http``.
The coordinator must also be configured with
``http-server.authentication.allow-insecure-over-http=true``.
"""

def __init__(
Expand Down