Install & Compatibility
Where this runs
tested against v0.8.4 · 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
muslpy 3.10–3.95 runs
installs and imports cleanly · install 0.0s · import 0.434s · 22.2MB
glibcpy 3.10–3.95 runs
installs and imports cleanly · install 2.3s · import 0.410s · 23MB
20MB installed
● package 20MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
connect
✓ from prestodb.dbapi import connect
The primary function to establish a connection to Presto.
BasicAuthentication
✓ from prestodb.auth import BasicAuthentication
Used for authenticating with Presto using username and password.
IsolationLevel
✓ from prestodb.transaction import IsolationLevel
Enum for setting transaction isolation levels.
PrestoQueryError
✓ from prestodb.exceptions import PrestoQueryError
Specific exception for Presto query-related errors, inheriting from base Exception.
This quickstart demonstrates how to establish a connection to a Presto server using the DBAPI interface, execute a simple query, and fetch the results. It includes optional basic authentication and uses environment variables for configuration, making it suitable for secure execution in various environments.
import os
from prestodb.dbapi import connect
from prestodb.auth import BasicAuthentication
host = os.environ.get('PRESTO_HOST', 'localhost')
port = int(os.environ.get('PRESTO_PORT', 8080))
user = os.environ.get('PRESTO_USER', 'the-user')
password = os.environ.get('PRESTO_PASSWORD', '') # Only if basic auth is needed
catalog = os.environ.get('PRESTO_CATALOG', 'the-catalog')
schema = os.environ.get('PRESTO_SCHEMA', 'the-schema')
auth = None
if password:
auth = BasicAuthentication(user, password)
try:
conn = connect(
host=host,
port=port,
user=user,
catalog=catalog,
schema=schema,
http_scheme=os.environ.get('PRESTO_HTTP_SCHEME', 'http'),
auth=auth
)
cur = conn.cursor()
cur.execute('SELECT * FROM system.runtime.nodes')
rows = cur.fetchall()
print("Successfully connected to Presto and fetched data.")
for row in rows:
print(row)
cur.close()
conn.close()
except Exception as e:
print(f"An error occurred: {e}")
Debug
Known issues
gotchaConfusion with Trino/PrestoSQL Clients: Users often confuse `presto-python-client` (designed for PrestoDB) with clients for Trino (formerly PrestoSQL). Ensure you are installing and using `presto-python-client` if your backend is PrestoDB, and not `trino` or `presto-client` packages, which serve Trino clusters.fixVerify your Presto server type (PrestoDB vs. Trino) and install the corresponding client library (`presto-python-client` for PrestoDB, `trino` for Trino).
affects: All versions
deprecatedOlder Python Version Support: As of version 0.8.4, the library officially supports Python 2.7, 3.5, 3.6, and 3.7. While it may function on newer Python versions (3.8+), these older versions are approaching or past their end-of-life and may not be actively tested or fully compatible with future changes.fixDevelop and test your application against a compatible Python version, ideally within the officially supported range. Be prepared for potential compatibility issues if using newer Python interpreters.
affects: All versions
gotcha`Cursor.fetchmany()` Default Behavior: By default, the `Cursor.fetchmany()` method retrieves only a single row. For efficient retrieval of multiple rows in batches, it is crucial to explicitly set `prestodb.dbapi.Cursor.arraysize` to the desired number of rows before calling `fetchmany()`.fixSet `cursor.arraysize = <desired_batch_size>` before calling `cursor.fetchmany()` to retrieve more than one row at a time.
affects: All versions
gotchaAutocommit Mode vs. Explicit Transactions: The client operates in autocommit mode by default. To enable explicit transaction management (e.g., `commit()` or `rollback()`), the `isolation_level` parameter in `prestodb.dbapi.connect()` must be set to a value other than `IsolationLevel.AUTOCOMMIT`, such as `IsolationLevel.READ_COMMITTED`.fixWhen creating a connection, specify `isolation_level=IsolationLevel.READ_COMMITTED` (or another desired level) to enable transaction control.
affects: All versions
gotchaSSL/TLS Certificate Verification Issues: When connecting to Presto via HTTPS, especially with self-signed certificates, `SSLCertVerificationError` is a common issue. This occurs if the client cannot verify the server's certificate.fixEnsure the `http_scheme` is set to 'https'. If using self-signed certificates, you may need to provide a `ca_bundle` path to the `auth` object or, for testing purposes only, disable verification by setting `conn._http_session.verify = False` (not recommended for production).
affects: All versions using HTTPS
gotchaConnection Timeouts and Refused Connections: Errors like `CONNECTION_TIMEOUT` or 'Connection Refused' typically indicate underlying network issues (firewalls, routing), an unresponsive or overloaded Presto server, or incorrect `host` and `port` configurations in the connection string.fixVerify network connectivity between client and server (e.g., using `ping` or `telnet`). Confirm the Presto server is running and accessible, and double-check the `host` and `port` parameters in your `connect()` call.
affects: All versions
Errors
Common errors & fixes
ModuleNotFoundError: No module named 'prestodb'
The 'presto-python-client' library, which exposes the 'prestodb' module, is not installed or is not available in the Python environment where the code is being executed.
fixInstall the library using pip: `pip install presto-python-client`
requests.exceptions.ConnectionError: ('Connection aborted.', RemoteDisconnected('Remote end closed connection without response'))
The Python client failed to establish or maintain a connection with the Presto server, often due to the server not running, incorrect host/port, network connectivity issues, or firewall restrictions. Other common ConnectionError messages include 'Connection refused' or 'Failed to establish a new connection'.
fixVerify that the Presto server is running and accessible from the client machine. Double-check the `host` and `port` parameters in your `prestodb.dbapi.connect()` call. Use tools like `curl` or `nc` to test network connectivity to the Presto server's host and port.
requests.exceptions.SSLError: HTTPSConnectionPool(...) (Caused by SSLError(SSLError("bad handshake: Error([('SSL routines', 'tls_process_server_certificate', 'certificate verify failed')])")))
The client is unable to verify the SSL/TLS certificate presented by the Presto server, typically because the server uses a self-signed certificate or one issued by an untrusted Certificate Authority.
fixProvide the path to your certificate file via `conn._http_session.verify = '/path/to/cert.pem'` or, if you understand and accept the security risks, disable SSL verification using `conn._http_session.verify = False` in your connection object.
AUTHENTICATION_FAILED
The credentials (username, password, or Kerberos configuration) provided by the client are incorrect or do not match the authentication method configured on the Presto server.
fixVerify the `user` and `password` parameters in your `prestodb.dbapi.connect()` call, or ensure your Kerberos configuration (if used) is correctly set up. Consult Presto server logs for more specific authentication failure details.
Upgrade
Version history
0.8.4latest on PyPI · released Sep 7, 2023
Audit
Dependencies
clickrequiredRequired for command-line utilities or internal components.
ipaddressrequiredUsed for IP address handling, likely for network communication.
requestsrequiredCore library for HTTP communication with the Presto server.
sixrequiredPython 2 and 3 compatibility utility.
typingrequiredTyping hints support (especially for Python 3.5+).
requests-kerberosoptionalRequired for Kerberos authentication.
google-authoptionalRequired for OAuth authentication.