Install & Compatibility
Where this runs
tested against v3.0.1 · 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
py 3.10
✕ build_error
✓ 2.03s
py 3.11
✕ build_error
✓ 1.9s
py 3.12
✕ build_error
✓ 1.8s
py 3.13
✕ build_error
✓ 1.75s
py 3.9
✕ build_error
2/4 runs
28MB installed
● package 28MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
connect
✓ from pyathenajdbc import connect
✗ from pyathenajdbc.connection import Connection
The primary entry point is the connect function, following DB API 2.0 standards.
Connects to Amazon Athena using default AWS credentials and executes a simple query. The `S3OutputLocation` is mandatory for Athena query results and should be configured. Credentials can be passed explicitly but are often resolved automatically by the `DefaultAWSCredentialsProviderChain`.
import os
from pyathenajdbc import connect
# Ensure AWS credentials (e.g., AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY)
# and region (AWS_REGION) are set via environment variables or boto3 config.
# S3OutputLocation is required for Athena query results.
# It's recommended to set it via an environment variable.
# Example: export AWS_ATHENA_S3_OUTPUT_LOCATION='s3://your-athena-query-results-bucket/'
s3_output_location = os.environ.get('AWS_ATHENA_S3_OUTPUT_LOCATION', '')
if not s3_output_location:
raise ValueError("AWS_ATHENA_S3_OUTPUT_LOCATION environment variable must be set.")
try:
conn = connect(
AwsRegion=os.environ.get('AWS_REGION', 'us-east-1'),
Schema='default', # Your Athena database name
S3OutputLocation=s3_output_location,
# User=os.environ.get('AWS_ACCESS_KEY_ID'), # Optional if using default credential chain
# Password=os.environ.get('AWS_SECRET_ACCESS_KEY') # Optional if using default credential chain
)
with conn.cursor() as cursor:
cursor.execute("SELECT 1 as one_value")
row = cursor.fetchone()
print(f"Result from SELECT 1: {row}")
cursor.execute("SHOW TABLES")
tables = cursor.fetchall()
print(f"Tables in 'default' schema: {tables}")
finally:
if 'conn' in locals() and conn:
conn.close()
Debug
Known issues
breakingVersion 3.0.0 dropped support for Python 2.7 and Python 3.5. It also redesigned Formatter and Converter classes, which might affect custom type handling.fixUpgrade to Python 3.6.1 or newer. Review custom formatter/converter implementations for compatibility with the new interfaces.
affects: >=3.0.0
breakingVersion 2.1.0 changed the argument names for the `connect` method to align with the JDBC driver's Driver Configuration Options. For example, `access_key` became `User`, `secret_key` became `Password`, `region_name` became `AwsRegion`, `schema_name` became `Schema`, and `s3_staging_dir` became `S3OutputLocation`.fixUpdate `connect` call arguments in your code to use the new names. Refer to the official JDBC driver documentation or the library's README for the full list of argument changes.
affects: >=2.1.0
gotchaThe Amazon Athena JDBC driver download URL changed in v3.0.0 (for driver 2.0.15). If you are behind a strict firewall or proxy that whitelists specific URLs, this change might prevent the library from automatically downloading the driver JAR.fixEnsure that network access to the new S3 endpoint for the JDBC driver (e.g., `https://s3.amazonaws.com/athena-downloads/drivers/JDBC/SimbaAthenaJDBC-2.0.15.1000/AthenaJDBC42.jar`) is permitted.
affects: >=3.0.0
gotchaPyAthenaJDBC relies on JPype1 for its Java bridge. Historically, there have been specific JPype1 version incompatibilities (e.g., v2.0.6 pinned JPype1 to <=0.7.1). While newer versions aim for broader compatibility, always check release notes when upgrading either library.fixIf encountering issues, consult `pyathenajdbc` and `JPype1` release notes for known compatibility ranges. You might need to pin `JPype1` to a specific version or upgrade `pyathenajdbc`.
affects: <3.0.0 (historically)
gotchaWhile `S3OutputLocation` (formerly `s3_staging_dir`) was made optional in `connect` method since v2.0.8, Athena queries fundamentally require an S3 location to store query results. Omitting it from `connect` means it must be configured at the Athena Workgroup level or other default settings, otherwise, queries will fail.fixAlways ensure an `S3OutputLocation` is specified either in the `connect` call or through your Athena Workgroup configuration to avoid query execution errors.
affects: All versions
Errors
Common errors & fixes
java.lang.RuntimeException: Class com.amazonaws.athena.jdbc.AthenaDriver not found
The Amazon Athena JDBC driver JAR file is either not found in the specified path, or the `driver_path` parameter in the `connect` call is incorrect, or the Java environment cannot locate the class within the JAR.
fixEnsure the Athena JDBC driver JAR file is downloaded and its full path is correctly provided to the `driver_path` argument in `pyathenajdbc.connect()`. Also, verify that a compatible Java Runtime Environment (JRE) or Java Development Kit (JDK) (Java 8 or later) is installed and accessible in the system's PATH or `JAVA_HOME` environment variable.
JPypeException: Could not start JVM
JPype, which `pyathenajdbc` relies on, failed to initialize the Java Virtual Machine. This can be due to an incompatible Java version, an incorrectly set `JAVA_HOME` environment variable, or conflicts with the JPype1 library itself (e.g., using an outdated JPype1 version with a newer Python/Java).
fixVerify that Java 8 or a newer compatible version (e.g., Java 11 for recent JPype versions) is installed and that the `JAVA_HOME` environment variable is correctly pointing to your Java installation. Ensure `JPype1` is installed (or downgraded/upgraded if recent changes cause issues), and if necessary, specify the JVM path explicitly in the `connect` call using `jvm_path`.
No matching overloads found for static java.sql.DriverManager.getConnection()
This error typically occurs when the arguments passed to the `pyathenajdbc.connect()` method, which are then passed to the underlying Java `DriverManager.getConnection()` method, have incorrect types or are in an unexpected format, especially when connection properties are not passed as strings.
fixEnsure all connection parameters (e.g., `s3_staging_dir`, `access_key`, `secret_key`, `region_name`) are passed as string types. Review the `pyathenajdbc` documentation for the exact expected types for each argument.
java.sql.SQLException: [...] The request signature we calculated does not match the signature you provided. Check your AWS Secret Access Key
This indicates an authentication failure with AWS Athena. The AWS access key ID, secret access key, or session token provided in the connection parameters are incorrect, expired, or do not have the necessary permissions to access Athena and the specified S3 staging directory.
fixDouble-check your AWS `access_key` and `secret_key` for typos. Ensure the IAM user or role associated with these credentials has permissions for `athena:StartQueryExecution`, `athena:GetQueryExecution`, `s3:GetObject`, `s3:ListBucket`, and `s3:PutObject` on the S3 staging bucket. If using temporary credentials, ensure the `session_token` is also provided and valid.
AttributeError: 'module' object has no attribute 'connect'
This generic Python error often arises if `pyathenajdbc.connect` is not imported correctly, or if there is a naming conflict (e.g., a local file named `pyathenajdbc.py` or a function named `connect` is shadowing the library's function). It can also happen if `pyathenajdbc` itself wasn't installed correctly.
fixEnsure you are importing `connect` from `pyathenajdbc` using `from pyathenajdbc import connect`. Check for any local files or variables that might be inadvertently named `pyathenajdbc` or `connect` that could cause a module or name collision. Verify the `pyathenajdbc` library is properly installed via `pip install pyathenajdbc`.
Upgrade
Version history
3.0.1latest on PyPI · released Dec 31, 2020
Audit
Dependencies
JPype1requiredRequired for bridging Python with the Java JDBC driver.
boto3optionalUsed for AWS credential resolution (via DefaultAWSCredentialsProviderChain) and S3 interactions.
SQLAlchemyoptionalOptional, if using PyAthenaJDBC as a SQLAlchemy dialect.
pandasoptionalOptional, for integrations like `pandas.to_sql`.