"""DB API 2.0 connection to Amazon Athena."""
from __future__ import annotations
import logging
import os
import threading
import time
from collections.abc import Callable
from functools import partial
from typing import (
TYPE_CHECKING,
Any,
ClassVar,
Generic,
TypeVar,
cast,
overload,
)
import botocore.session
from boto3.session import Session
from botocore.config import Config
from botocore.credentials import CredentialProvider, CredentialResolver, RefreshableCredentials
import pyathena
from pyathena.common import BaseCursor, CursorIterator, OnPollCallback
from pyathena.converter import Converter
from pyathena.cursor import Cursor
from pyathena.error import NotSupportedError, ProgrammingError
from pyathena.formatter import DefaultParameterFormatter, Formatter
from pyathena.glue import GlueMetadataClient
from pyathena.util import RetryConfig
if TYPE_CHECKING:
from botocore.client import BaseClient
_logger = logging.getLogger(__name__)
ConnectionCursor = TypeVar("ConnectionCursor", bound=BaseCursor)
FunctionalCursor = TypeVar("FunctionalCursor", bound=BaseCursor)
class _STSCredentialProvider(CredentialProvider):
"""Provide a connection's STS credentials to its botocore session."""
METHOD = "pyathena-sts"
def __init__(self, credentials: RefreshableCredentials) -> None:
"""Initialize the provider.
Args:
credentials: The credentials that STS returned, which refresh themselves.
"""
super().__init__()
self._credentials = credentials
def load(self) -> RefreshableCredentials:
"""Return the credentials.
Returns:
The refreshable credentials.
"""
return self._credentials
[docs]
class Connection(Generic[ConnectionCursor]):
"""A DB API 2.0 compliant connection to Amazon Athena.
The Connection class represents a database session and provides methods to
create cursors for executing SQL queries against Amazon Athena. It handles
authentication, session management, and query result storage in S3.
This class follows the Python Database API Specification v2.0 (PEP 249)
and provides a familiar interface for database operations.
Attributes:
s3_staging_dir: S3 location where query results are stored.
region_name: AWS region name.
schema_name: Default database/schema name for queries.
catalog_name: Data catalog name (typically "awsdatacatalog").
work_group: Athena workgroup name.
poll_interval: Interval in seconds for polling query status.
encryption_option: S3 encryption option for query results.
kms_key: KMS key for encryption when applicable.
kill_on_interrupt: Whether to cancel queries on interrupt signals.
result_reuse_enable: Whether to enable Athena's result reuse feature.
result_reuse_minutes: Minutes to reuse cached results.
Example:
>>> conn = Connection(
... s3_staging_dir='s3://my-bucket/staging/',
... region_name='us-east-1',
... schema_name='mydatabase'
... )
>>> with conn:
... cursor = conn.cursor()
... cursor.execute("SELECT COUNT(*) FROM mytable")
... result = cursor.fetchone()
Note:
Either s3_staging_dir or work_group must be specified. If using a
workgroup, it must have a result location configured unless
s3_staging_dir is also provided. For workgroups with managed query
result storage, pass ``s3_staging_dir=""`` to skip the environment
variable fallback.
"""
_ENV_S3_STAGING_DIR: str = "AWS_ATHENA_S3_STAGING_DIR"
_ENV_WORK_GROUP: str = "AWS_ATHENA_WORK_GROUP"
_SESSION_PASSING_ARGS: ClassVar[list[str]] = [
"aws_access_key_id",
"aws_secret_access_key",
"aws_session_token",
"region_name",
"botocore_session",
"profile_name",
]
_CLIENT_PASSING_ARGS: ClassVar[list[str]] = [
"aws_access_key_id",
"aws_secret_access_key",
"aws_session_token",
"api_version",
"use_ssl",
"verify",
"endpoint_url",
"region_name",
"config",
]
# The arguments that sign the STS requests of role_arn and serial_number, which the
# session of the connection replaces with the credentials that STS returns.
_STS_SOURCE_ARGS: ClassVar[tuple[str, ...]] = (
"aws_access_key_id",
"aws_secret_access_key",
"aws_session_token",
"botocore_session",
)
@overload
def __init__(
self: Connection[Cursor],
*,
s3_staging_dir: str | None = ...,
region_name: str | None = ...,
schema_name: str | None = ...,
catalog_name: str | None = ...,
work_group: str | None = ...,
poll_interval: float = ...,
encryption_option: str | None = ...,
kms_key: str | None = ...,
profile_name: str | None = ...,
role_arn: str | None = ...,
role_session_name: str = ...,
external_id: str | None = ...,
serial_number: str | None = ...,
duration_seconds: int = ...,
converter: Converter | None = ...,
formatter: Formatter | None = ...,
retry_config: RetryConfig | None = ...,
cursor_class: None = ...,
cursor_kwargs: dict[str, Any] | None = ...,
kill_on_interrupt: bool = ...,
session: Session | None = ...,
config: Config | None = ...,
result_reuse_enable: bool = ...,
result_reuse_minutes: int = ...,
on_start_query_execution: Callable[[str], None] | None = ...,
on_poll: OnPollCallback | None = ...,
glue_metadata_fallback: bool = ...,
s3_config: Config | None = ...,
**kwargs,
) -> None: ...
@overload
def __init__(
self: Connection[ConnectionCursor],
*,
s3_staging_dir: str | None = ...,
region_name: str | None = ...,
schema_name: str | None = ...,
catalog_name: str | None = ...,
work_group: str | None = ...,
poll_interval: float = ...,
encryption_option: str | None = ...,
kms_key: str | None = ...,
profile_name: str | None = ...,
role_arn: str | None = ...,
role_session_name: str = ...,
external_id: str | None = ...,
serial_number: str | None = ...,
duration_seconds: int = ...,
converter: Converter | None = ...,
formatter: Formatter | None = ...,
retry_config: RetryConfig | None = ...,
cursor_class: type[ConnectionCursor] = ...,
cursor_kwargs: dict[str, Any] | None = ...,
kill_on_interrupt: bool = ...,
session: Session | None = ...,
config: Config | None = ...,
result_reuse_enable: bool = ...,
result_reuse_minutes: int = ...,
on_start_query_execution: Callable[[str], None] | None = ...,
on_poll: OnPollCallback | None = ...,
glue_metadata_fallback: bool = ...,
s3_config: Config | None = ...,
**kwargs,
) -> None: ...
[docs]
def __init__(
self,
*,
s3_staging_dir: str | None = None,
region_name: str | None = None,
schema_name: str | None = "default",
catalog_name: str | None = "awsdatacatalog",
work_group: str | None = None,
poll_interval: float = 1,
encryption_option: str | None = None,
kms_key: str | None = None,
profile_name: str | None = None,
role_arn: str | None = None,
role_session_name: str = f"PyAthena-session-{int(time.time())}",
external_id: str | None = None,
serial_number: str | None = None,
duration_seconds: int = 3600,
converter: Converter | None = None,
formatter: Formatter | None = None,
retry_config: RetryConfig | None = None,
cursor_class: type[ConnectionCursor] | None = None,
cursor_kwargs: dict[str, Any] | None = None,
kill_on_interrupt: bool = True,
session: Session | None = None,
config: Config | None = None,
result_reuse_enable: bool = False,
result_reuse_minutes: int = CursorIterator.DEFAULT_RESULT_REUSE_MINUTES,
on_start_query_execution: Callable[[str], None] | None = None,
on_poll: OnPollCallback | None = None,
glue_metadata_fallback: bool = True,
s3_config: Config | None = None,
**kwargs,
) -> None:
"""Initialize a new Athena database connection.
Args:
s3_staging_dir: S3 location to store query results. Required if not
using workgroups or if workgroup doesn't have result location.
None uses the ``AWS_ATHENA_S3_STAGING_DIR`` environment variable.
Pass an empty string to explicitly disable S3 staging and skip
the ``AWS_ATHENA_S3_STAGING_DIR`` environment variable fallback.
This is required when connecting to a workgroup with managed
query result storage enabled.
region_name: AWS region name. Uses default region if not specified.
schema_name: Default database/schema name. Defaults to "default".
catalog_name: Data catalog name. Defaults to "awsdatacatalog".
work_group: Athena workgroup name. Can substitute for s3_staging_dir
if workgroup has result location configured.
None uses the ``AWS_ATHENA_WORK_GROUP`` environment variable.
Pass an empty string to skip that environment variable fallback
and leave the workgroup unset.
poll_interval: Seconds between query status polls. Defaults to 1.0.
encryption_option: S3 encryption for results ("SSE_S3", "SSE_KMS", "CSE_KMS").
kms_key: KMS key ID when using SSE_KMS or CSE_KMS encryption.
profile_name: AWS profile name for authentication.
role_arn: IAM role ARN to assume for authentication. The session and
clients of the connection use the role's credentials, which are
requested again before they expire; the profile, credential and
``botocore_session`` arguments sign only the AssumeRole requests.
role_session_name: Session name when assuming IAM role.
external_id: External ID for role assumption (if required by role).
serial_number: MFA device serial number, for role assumption with
``role_arn`` or for GetSessionToken without it. Each request for
credentials, at connection and once they are about to expire,
prompts for an MFA code with ``input()``; the other threads that
need them wait.
duration_seconds: The duration in seconds of the credentials of
``role_arn`` or ``serial_number``. Defaults to 3600.
converter: Custom type converter. Uses DefaultTypeConverter if None.
formatter: Custom parameter formatter. Uses DefaultParameterFormatter if None.
retry_config: Retry configuration for API calls. Uses default if None.
cursor_class: Default cursor class for this connection.
cursor_kwargs: Default keyword arguments for cursor creation.
Arguments passed to ``cursor()`` override the same keys.
kill_on_interrupt: Cancel running queries on interrupt. Defaults to True.
session: Pre-configured boto3 Session. Creates new session if None.
config: Boto3 Config object for client configuration.
result_reuse_enable: Enable Athena query result reuse. Defaults to False.
result_reuse_minutes: Minutes to reuse cached results.
on_start_query_execution: Callback invoked with each query ID before the cursor
waits for the query, as for the ``execute()`` argument of the same name.
on_poll: Callback invoked once per poll iteration with the current
execution object (``AthenaQueryExecution``, or
``AthenaCalculationExecutionStatus`` for Spark). Useful for
monitoring live query progress. Defaults to None.
glue_metadata_fallback: In ``AwsDataCatalog`` and S3 Tables catalogs,
answer a throttled table-metadata, table-listing or
database-listing request from the AWS Glue Data Catalog before
retrying it. Defaults to True.
s3_config: Botocore Config options for the S3 client only, such as
``max_pool_connections``. They are merged over ``config``.
**kwargs: Additional arguments passed to boto3 Session and client.
Raises:
ProgrammingError: If neither s3_staging_dir nor work_group is provided.
Note:
Either s3_staging_dir or work_group must be specified. Environment
variables AWS_ATHENA_S3_STAGING_DIR and AWS_ATHENA_WORK_GROUP are
checked only when the corresponding argument is omitted or None.
An explicit empty string disables that fallback and becomes None.
When using a workgroup with managed query result storage, pass
``s3_staging_dir=""`` to prevent the environment variable fallback
from sending a ``ResultConfiguration`` that conflicts with
``ManagedQueryResultsConfiguration``.
"""
self._kwargs = {
**kwargs,
"role_arn": role_arn,
"role_session_name": role_session_name,
"external_id": external_id,
"serial_number": serial_number,
"duration_seconds": duration_seconds,
}
if s3_staging_dir is not None:
self.s3_staging_dir: str | None = s3_staging_dir or None
else:
self.s3_staging_dir = os.getenv(self._ENV_S3_STAGING_DIR)
self.region_name = region_name
self.schema_name = schema_name
self.catalog_name = catalog_name
if work_group is not None:
self.work_group: str | None = work_group or None
else:
self.work_group = os.getenv(self._ENV_WORK_GROUP)
self.poll_interval = poll_interval
self.encryption_option = encryption_option
self.kms_key = kms_key
self.profile_name = profile_name
self.config: Config | None = config if config else Config()
if not self.s3_staging_dir and not self.work_group:
raise ProgrammingError("Required argument `s3_staging_dir` or `work_group` not found.")
if self.s3_staging_dir and not self.s3_staging_dir.endswith("/"):
self.s3_staging_dir = f"{self.s3_staging_dir}/"
# Whether the credentials come from the session alone, because it was given or
# its STS credentials are refreshed, so that the arguments do not reproduce them.
self._credentials_from_session = bool(session or role_arn or serial_number)
# The client of the STS requests of role_arn or serial_number, closed with the
# connection.
self._sts_client: BaseClient | None = None
if session:
self._session = session
elif role_arn or serial_number:
# The profile, credential and botocore session arguments sign only the STS
# requests, which one client sends; the session and clients of the
# connection use the credentials that STS returns.
self._sts_client = Session(
region_name=self.region_name,
profile_name=self.profile_name,
**self._session_kwargs,
).client("sts", region_name=self.region_name, config=self.config, **self._client_kwargs)
self.profile_name = None
for key in self._STS_SOURCE_ARGS:
self._kwargs.pop(key, None)
self._session = self._create_refreshable_session(
self._sts_client, duration_seconds, prompts=bool(serial_number)
)
else:
self._session = Session(
region_name=self.region_name,
profile_name=self.profile_name,
**self._session_kwargs,
)
self._add_user_agent(self.config)
self.s3_config: Config = self.config.merge(s3_config) if s3_config else self.config
self._add_user_agent(self.s3_config)
self._client = self._session.client(
"athena", region_name=self.region_name, config=self.config, **self._client_kwargs
)
# Built on first use, once per connection even when several threads
# need it at the same time.
self._s3_client_lock = threading.Lock()
self._s3_client: BaseClient | None = None
self._converter = converter
self._formatter = formatter if formatter else DefaultParameterFormatter()
self._retry_config = retry_config if retry_config else RetryConfig()
self.cursor_class = cursor_class if cursor_class else cast(type[ConnectionCursor], Cursor)
self.cursor_kwargs = cursor_kwargs if cursor_kwargs else {}
self.kill_on_interrupt = kill_on_interrupt
self.result_reuse_enable = result_reuse_enable
self.result_reuse_minutes = result_reuse_minutes
self.on_start_query_execution = on_start_query_execution
self.on_poll = on_poll
self.glue_metadata_fallback = glue_metadata_fallback
self._glue = GlueMetadataClient(
self._session, self.region_name, self.config, self._client_kwargs
)
def _create_refreshable_session(
self, sts_client: BaseClient, duration_seconds: int, prompts: bool
) -> Session:
"""Create the session whose credentials STS returns and refreshes before they expire.
The credentials are requested now, and again once less than a quarter of
``duration_seconds``, at most 15 minutes, is left before they expire; they
must be refreshed once less than a sixth, at most 10 minutes, is left.
botocore's defaults of 15 and 10 minutes would request new credentials on
every use with a ``duration_seconds`` of 15 minutes. A request that prompts
for an MFA code is made only once the refresh is mandatory, since botocore
retries a failed advisory refresh on every use of the credentials.
Args:
sts_client: The client that sends the STS requests.
duration_seconds: The duration of the credentials.
prompts: Whether each request prompts for an MFA code.
Returns:
A session whose clients sign their requests with the refreshed credentials.
"""
request_credentials = partial(self._request_credentials, sts_client)
mandatory_timeout = min(10 * 60, duration_seconds // 6)
credentials = RefreshableCredentials.create_from_metadata(
metadata=request_credentials(),
refresh_using=request_credentials,
method=_STSCredentialProvider.METHOD,
advisory_timeout=mandatory_timeout if prompts else min(15 * 60, duration_seconds // 4),
mandatory_timeout=mandatory_timeout,
)
botocore_session = botocore.session.Session()
# The only credentials of the session: botocore's chain of providers is not used.
botocore_session.register_component(
"credential_provider", CredentialResolver([_STSCredentialProvider(credentials)])
)
return Session(
region_name=self.region_name,
botocore_session=botocore_session,
**self._session_kwargs,
)
def _request_credentials(self, sts_client: BaseClient) -> dict[str, str]:
"""Request credentials from STS with the connection's ``role_arn`` or ``serial_number``.
With ``serial_number``, each request prompts for an MFA code (see
``_assume_role()`` and ``_get_session_token()``).
Args:
sts_client: The client that sends the STS requests.
Returns:
The credentials as botocore's credential metadata: ``access_key``,
``secret_key``, ``token``, and ``expiry_time``.
"""
if self._kwargs["role_arn"]:
creds = self._assume_role(
client=sts_client,
role_arn=self._kwargs["role_arn"],
role_session_name=self._kwargs["role_session_name"],
external_id=self._kwargs["external_id"],
serial_number=self._kwargs["serial_number"],
duration_seconds=self._kwargs["duration_seconds"],
)
else:
creds = self._get_session_token(
client=sts_client,
serial_number=self._kwargs["serial_number"],
duration_seconds=self._kwargs["duration_seconds"],
)
return {
"access_key": creds["AccessKeyId"],
"secret_key": creds["SecretAccessKey"],
"token": creds["SessionToken"],
"expiry_time": creds["Expiration"].isoformat(),
}
@staticmethod
def _add_user_agent(config: Config) -> None:
"""Add PyAthena's user agent to a botocore config unless it has it.
Args:
config: The config to update in place.
"""
if not config.user_agent_extra or pyathena.user_agent_extra not in config.user_agent_extra:
config.user_agent_extra = (
f"{pyathena.user_agent_extra}"
f"{' ' + config.user_agent_extra if config.user_agent_extra else ''}"
)
def _assume_role(
self,
client: BaseClient,
role_arn: str,
role_session_name: str,
external_id: str | None,
serial_number: str | None,
duration_seconds: int,
) -> dict[str, Any]:
"""Assume an IAM role and return temporary credentials.
Uses AWS STS to assume the specified IAM role and obtain temporary
security credentials. Supports multi-factor authentication (MFA)
when a serial number is provided.
Args:
client: The STS client, with the connection's profile and credential
arguments.
role_arn: ARN of the IAM role to assume.
role_session_name: Name for the role session.
external_id: External ID for additional security when assuming role.
serial_number: MFA device serial number. If provided, prompts for MFA code.
duration_seconds: Duration of the temporary credentials in seconds.
Returns:
Dictionary containing temporary AWS credentials with keys:
'AccessKeyId', 'SecretAccessKey', 'SessionToken', 'Expiration'.
Note:
When MFA is required (serial_number provided), this method will
prompt for an MFA token code via input().
"""
request = {
"RoleArn": role_arn,
"RoleSessionName": role_session_name,
"DurationSeconds": duration_seconds,
}
if external_id:
request.update(
{
"ExternalId": external_id,
}
)
if serial_number:
token_code = input("Enter the MFA code: ")
request.update(
{
"SerialNumber": serial_number,
"TokenCode": token_code,
}
)
response = client.assume_role(**request)
creds: dict[str, Any] = response["Credentials"]
return creds
def _get_session_token(
self,
client: BaseClient,
serial_number: str | None,
duration_seconds: int,
) -> dict[str, Any]:
"""Get session token using MFA authentication.
Obtains temporary security credentials by providing MFA authentication.
This is used when MFA is required but role assumption is not needed.
Args:
client: The STS client, with the connection's profile and credential
arguments.
serial_number: MFA device serial number.
duration_seconds: Duration of the temporary credentials in seconds.
Returns:
Dictionary containing temporary AWS credentials with keys:
'AccessKeyId', 'SecretAccessKey', 'SessionToken', 'Expiration'.
Note:
This method will prompt for an MFA token code via input().
"""
token_code = input("Enter the MFA code: ")
request = {
"DurationSeconds": duration_seconds,
"SerialNumber": serial_number,
"TokenCode": token_code,
}
response = client.get_session_token(**request)
creds: dict[str, Any] = response["Credentials"]
return creds
@property
def _session_kwargs(self) -> dict[str, Any]:
"""Get session keyword arguments for AWS Session creation.
Returns:
Dictionary of filtered keyword arguments that are valid for
boto3 Session constructor.
"""
return {k: v for k, v in self._kwargs.items() if k in self._SESSION_PASSING_ARGS}
@property
def _client_kwargs(self) -> dict[str, Any]:
"""Get client keyword arguments for AWS client creation.
Returns:
Dictionary of filtered keyword arguments that are valid for
boto3 client constructor.
"""
return {k: v for k, v in self._kwargs.items() if k in self._CLIENT_PASSING_ARGS}
@property
def _s3_client_kwargs(self) -> dict[str, Any]:
"""Get client keyword arguments for S3 client creation.
Returns:
The client keyword arguments without Athena's ``endpoint_url``
and ``api_version``.
"""
return {
k: v for k, v in self._client_kwargs.items() if k not in ("endpoint_url", "api_version")
}
@property
def session(self) -> Session:
"""Get the boto3 session used for AWS API calls.
Returns:
The configured boto3 Session object.
"""
return self._session
@property
def client(self) -> BaseClient:
"""Get the boto3 Athena client used for query operations.
Returns:
The configured boto3 Athena client.
"""
return self._client
@property
def s3_client(self) -> BaseClient:
"""The S3 client shared by the connection's result sets, filesystems and Spark cursors.
It is built on first use from the connection's session, region,
``s3_config`` and client arguments, except Athena's ``endpoint_url``
and ``api_version``.
"""
with self._s3_client_lock:
if self._s3_client is None:
self._s3_client = self._session.client(
"s3",
region_name=self.region_name,
config=self.s3_config,
**self._s3_client_kwargs,
)
return self._s3_client
@property
def retry_config(self) -> RetryConfig:
"""Get the retry configuration for AWS API calls.
Returns:
The RetryConfig object that controls retry behavior for failed requests.
"""
return self._retry_config
[docs]
def __enter__(self):
"""Enter the runtime context for the connection.
Returns:
Self for use in context manager protocol.
"""
return self
[docs]
def __exit__(self, exc_type, exc_val, exc_tb):
"""Exit the runtime context and close the connection.
Args:
exc_type: Exception type if an exception occurred.
exc_val: Exception value if an exception occurred.
exc_tb: Exception traceback if an exception occurred.
"""
self.close()
@overload
def cursor(self, cursor: None = ..., **kwargs) -> ConnectionCursor: ...
@overload
def cursor(self, cursor: type[FunctionalCursor], **kwargs) -> FunctionalCursor: ...
[docs]
def cursor(
self, cursor: type[FunctionalCursor] | None = None, **kwargs
) -> FunctionalCursor | ConnectionCursor:
"""Create a new cursor object for executing queries.
Creates and returns a cursor object that can be used to execute SQL
queries against Amazon Athena. The cursor inherits connection settings
but can be customized with additional parameters.
Args:
cursor: Custom cursor class to use. If not provided, uses the
connection's default cursor class.
**kwargs: Additional keyword arguments to pass to the cursor
constructor. These override the connection's ``cursor_kwargs``
and its defaults.
Returns:
A cursor object that can execute SQL queries.
Example:
>>> cursor = connection.cursor()
>>> cursor.execute("SELECT * FROM my_table LIMIT 10")
>>> results = cursor.fetchall()
# Using a custom cursor type
>>> from pyathena.pandas.cursor import PandasCursor
>>> pandas_cursor = connection.cursor(PandasCursor)
>>> df = pandas_cursor.execute("SELECT * FROM my_table").fetchall()
"""
return self._cursor(cursor, **{**self.cursor_kwargs, **kwargs})
def _cursor(
self, cursor: type[FunctionalCursor] | None, /, **kwargs: Any
) -> FunctionalCursor | ConnectionCursor:
"""Create a cursor without applying the connection's ``cursor_kwargs``.
Args:
cursor: The cursor class. If None, the connection's default cursor class.
**kwargs: The cursor constructor arguments. Omitted connection settings
default to the connection's values.
Returns:
The created cursor.
"""
_cursor = cursor or self.cursor_class
converter = kwargs.pop("converter", self._converter)
if not converter:
converter = _cursor.get_default_converter(kwargs.get("unload", False))
return _cursor(
connection=self,
converter=converter,
formatter=kwargs.pop("formatter", self._formatter),
retry_config=kwargs.pop("retry_config", self._retry_config),
s3_staging_dir=kwargs.pop("s3_staging_dir", self.s3_staging_dir),
schema_name=kwargs.pop("schema_name", self.schema_name),
catalog_name=kwargs.pop("catalog_name", self.catalog_name),
work_group=kwargs.pop("work_group", self.work_group),
poll_interval=kwargs.pop("poll_interval", self.poll_interval),
encryption_option=kwargs.pop("encryption_option", self.encryption_option),
kms_key=kwargs.pop("kms_key", self.kms_key),
kill_on_interrupt=kwargs.pop("kill_on_interrupt", self.kill_on_interrupt),
result_reuse_enable=kwargs.pop("result_reuse_enable", self.result_reuse_enable),
result_reuse_minutes=kwargs.pop("result_reuse_minutes", self.result_reuse_minutes),
on_start_query_execution=kwargs.pop(
"on_start_query_execution", self.on_start_query_execution
),
on_poll=kwargs.pop("on_poll", self.on_poll),
**kwargs,
)
def _internal_cursor(self, cursor: type[FunctionalCursor]) -> FunctionalCursor:
"""Create a cursor for queries that PyAthena runs on its own behalf.
Only the connection's ``cursor_kwargs`` that the cursor class accepts are
applied, leaving out options of the default cursor class such as ``unload``
of a DataFrame cursor. ``arraysize`` is left out too, since a DataFrame
cursor allows values above this cursor's page size limit. The cursor
class's default converter is used.
Args:
cursor: The cursor class.
Returns:
The created cursor.
"""
accepted = cursor._constructor_keyword_names() - {"arraysize"}
kwargs = {k: v for k, v in self.cursor_kwargs.items() if k in accepted}
kwargs["converter"] = cursor.get_default_converter()
return cast(FunctionalCursor, self._cursor(cursor, **kwargs))
[docs]
def close(self) -> None:
"""Close the connection.
Closes the network connections of the Athena client, of the STS client of
``role_arn`` or ``serial_number``, and of the Glue and S3 clients if they
were built. A client used after this opens new network connections.
Note:
This method is called automatically when using the connection
as a context manager (with statement).
"""
self._client.close()
if self._sts_client is not None:
self._sts_client.close()
self._glue.close()
with self._s3_client_lock:
if self._s3_client is not None:
self._s3_client.close()
[docs]
def commit(self) -> None:
"""Commit any pending transaction.
This method is provided for DB API 2.0 compatibility. Since Athena
does not support transactions, this method does nothing.
Note:
Athena queries are auto-committed and cannot be rolled back.
"""
[docs]
def rollback(self) -> None:
"""Rollback any pending transaction.
This method is required by DB API 2.0 but is not supported by Athena
since Athena does not support transactions.
Raises:
NotSupportedError: Always raised since transactions are not supported.
"""
raise NotSupportedError