feat: asyncio support (async wrapper, plugins, and SQLAlchemy dialects)

.github/workflows/integration_tests.yml

@@ -17,7 +17,7 @@ jobs:
     strategy:
       fail-fast: false
       matrix:
-        python-version: [ "3.11", "3.12", "3.13" ]
+        python-version: [ "3.11", "3.12", "3.13", "3.14"  ]
         environment: [ "mysql", "pg" ]
 
     steps:
@@ -71,7 +71,7 @@ jobs:
     strategy:
       fail-fast: false
       matrix:
-        python-version: [ "3.11", "3.12", "3.13" ]
+        python-version: [ "3.11", "3.12", "3.13", "3.14" ]
         environment: [ "mysql", "pg" ]
 
     steps:

.github/workflows/integration_tests_codebuild.yml

@@ -13,7 +13,7 @@ jobs:
     strategy:
       fail-fast: false
       matrix:
-        python-version: [ "3.11", "3.12", "3.13" ]
+        python-version: [ "3.11", "3.12", "3.13", "3.14" ]
         environment: [ "mysql", "pg" ]
 
     runs-on: ubuntu-latest

CHANGELOG.md

@@ -6,6 +6,7 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 ## [Unreleased]
 ### :magic_wand: Added
 * Python 3.14 support. ([PR #1252](https://github.com/aws/aws-advanced-python-wrapper/pull/1252))
+* Async (asyncio) counterpart of the wrapper (`aws_advanced_python_wrapper.aio`), targeting sync parity for the shipped plugins: failover v2, read/write splitting, EFM v2, IAM auth, AWS Secrets Manager, federated + Okta auth, Aurora connection tracker, cluster topology monitor, custom endpoint, stale DNS, Aurora initial connection strategy, simple read/write splitting, developer plugin, blue/green deployment, limitless, fastest-response strategy. Backed by psycopg async and aiomysql, with async SQLAlchemy support via `create_async_engine` (`postgresql+aws_wrapper_psycopg://` serves both sync and async; MySQL async uses `mysql+aws_wrapper_aiomysql://`). Includes `AsyncConnectionProvider`/`AsyncPooledConnectionProvider`, `AsyncSessionStateService`, an async IdP factory registry, and `release_resources_async()` for background-task teardown. ([PR #1257](https://github.com/aws/aws-advanced-python-wrapper/pull/1257))
 
 ### :bug: Fixed
 * Cross-thread use-after-free (SIGSEGV) when an offloaded query times out (e.g. during failover) and the connection is later closed or reused while the query is still running: on timeout the driver dialects now shut down the connection socket and wait for the worker to unwind before propagating, and leak rather than close a connection whose worker cannot be drained. ([PR #1252](https://github.com/aws/aws-advanced-python-wrapper/pull/1252))

README.md

@@ -147,6 +147,8 @@ The following table lists the connection properties used with the AWS Advanced P
 Technical documentation regarding the functionality of the AWS Advanced Python Wrapper will be maintained in this GitHub repository. Since the AWS Advanced Python Wrapper requires an underlying Python driver, please refer to the individual driver's documentation for driver-specific information.
 To find all the documentation and concrete examples on how to use the AWS Advanced Python Wrapper, please refer to the [AWS Advanced Python Wrapper Documentation](./docs/README.md) page.
 
+For SQLAlchemy integration (both PostgreSQL and MySQL), see [SQLAlchemy Support](./docs/using-the-python-wrapper/SqlAlchemySupport.md).
+
 ### Known Limitations
 
 #### Amazon RDS Blue/Green Deployments
@@ -214,7 +216,7 @@ For all other questions, please use [GitHub discussions](https://github.com/aws/
 
 1. Set up your environment by following the directions in the [Development Guide](./docs/development-guide/DevelopmentGuide.md).
 2. To contribute, first make a fork of this project. 
-3. Make any changes on your fork. Make sure you are aware of the requirements for the project (e.g. do not require Python 3.7 if we are supporting Python 3.10 - 3.13 (inclusive)).
+3. Make any changes on your fork. Make sure you are aware of the requirements for the project (e.g. do not require Python 3.7 if we are supporting Python 3.10 - 3.14 (inclusive)).
 4. Create a pull request from your fork. 
 5. Pull requests need to be approved and merged by maintainers into the main branch. <br />
 

aws_advanced_python_wrapper/aio/__init__.py

@@ -0,0 +1,45 @@
+#  Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
+#
+#  Licensed under the Apache License, Version 2.0 (the "License").
+#  You may not use this file except in compliance with the License.
+#  You may obtain a copy of the License at
+#
+#  http://www.apache.org/licenses/LICENSE-2.0
+#
+#  Unless required by applicable law or agreed to in writing, software
+#  distributed under the License is distributed on an "AS IS" BASIS,
+#  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+#  See the License for the specific language governing permissions and
+#  limitations under the License.
+
+"""Async counterparts of the sync wrapper classes.
+
+Structure:
+  - ``aio.wrapper`` -- ``AsyncAwsWrapperConnection`` (async connection facade)
+  - ``aio.plugin`` -- ``AsyncPlugin`` / ``AsyncConnectionProvider`` ABCs
+  - ``aio.driver_dialect`` -- the sole driver-specific interface
+    (``AsyncDriverDialect`` ABC + per-driver concrete dialects)
+  - ``aio.pooled_connection_provider`` -- ``AsyncPooledConnectionProvider``
+    (per-host, per-user async pool with sliding expiration)
+
+Typical usage (once SP-2 lands the implementation)::
+
+    from aws_advanced_python_wrapper.aio import AsyncAwsWrapperConnection
+
+    conn = await AsyncAwsWrapperConnection.connect(...)
+
+See the F3-B master spec for the overall design.
+"""
+
+from aws_advanced_python_wrapper.aio.cleanup import (register_shutdown_hook,
+                                                     release_resources_async)
+from aws_advanced_python_wrapper.aio.pooled_connection_provider import \
+    AsyncPooledConnectionProvider
+from aws_advanced_python_wrapper.aio.wrapper import AsyncAwsWrapperConnection
+
+__all__ = [
+    "AsyncAwsWrapperConnection",
+    "AsyncPooledConnectionProvider",
+    "release_resources_async",
+    "register_shutdown_hook",
+]

aws_advanced_python_wrapper/aio/_rws_failover_eviction.py

@@ -0,0 +1,110 @@
+#  Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
+#
+#  Licensed under the Apache License, Version 2.0 (the "License").
+#  You may not use this file except in compliance with the License.
+#  You may obtain a copy of the License at
+#
+#  http://www.apache.org/licenses/LICENSE-2.0
+#
+#  Unless required by applicable law or agreed to in writing, software
+#  distributed under the License is distributed on an "AS IS" BASIS,
+#  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+#  See the License for the specific language governing permissions and
+#  limitations under the License.
+
+"""Shared failover-eviction logic for the async read/write-splitting plugins.
+
+Async parity with the sync ``AbstractReadWriteSplittingPlugin`` (PR #1117 /
+#1229): when a ``FailoverError`` is raised while a command executes, the cached
+reader/writer connections must be evicted -- otherwise an internal-pool
+connection that failed over mid-query is returned to the pool stale, and a
+later checkout hands back a connection bound to a now-demoted instance.
+
+Both async RWS variants (:class:`AsyncReadWriteSplittingPlugin` and
+:class:`AsyncSimpleReadWriteSplittingPlugin`) mix this in. It expects the host
+class to define ``_plugin_service``, ``_reader_conn`` and ``_writer_conn``;
+``_reader_host_info`` / ``_writer_host_info`` are cleared too when present (the
+topology variant caches them; the simple variant uses fixed endpoint hosts).
+"""
+
+from __future__ import annotations
+
+import asyncio
+from typing import Any, Awaitable, Callable
+
+from aws_advanced_python_wrapper.errors import (FailoverError,
+                                                FailoverFailedError)
+from aws_advanced_python_wrapper.utils.log import Logger
+
+logger = Logger(__name__)
+
+
+class _AsyncRwsFailoverEvictionMixin:
+    """Failover-eviction helpers shared by the async RWS plugins."""
+
+    # Declared on the concrete plugin classes; annotated here for type checkers.
+    _plugin_service: Any
+    _reader_conn: Any
+    _writer_conn: Any
+    # The topology RWS variant caches these; the simple variant uses fixed
+    # endpoint hosts and never sets them. Declared as Any so each subclass may
+    # annotate them as Optional[HostInfo] without a variance conflict.
+    _reader_host_info: Any
+    _writer_host_info: Any
+
+    async def _execute_with_failover_eviction(
+            self,
+            method_name: str,
+            execute_func: Callable[..., Awaitable[Any]]) -> Any:
+        """Run ``execute_func`` and evict stale pooled conns on failover.
+
+        Sync parity: ``AbstractReadWriteSplittingPlugin.execute``.
+        ``FailoverFailedError`` -> no usable connection, so evict even the
+        in-use one; any other ``FailoverError`` (success /
+        transaction-resolution-unknown) means the wrapper reconnected, so evict
+        only the idle cached connections and keep the in-use one.
+        """
+        try:
+            return await execute_func()
+        except FailoverFailedError:
+            await self._close_connections(close_only_if_idle=False)
+            raise
+        except FailoverError:
+            logger.debug(
+                "ReadWriteSplittingPlugin.FailoverExceptionWhileExecutingCommand",
+                method_name)
+            await self._close_connections(close_only_if_idle=True)
+            raise
+
+    async def _close_connections(self, close_only_if_idle: bool = True) -> None:
+        await self._close_connection(self._reader_conn, close_only_if_idle)
+        await self._close_connection(self._writer_conn, close_only_if_idle)
+
+    async def _close_connection(
+            self,
+            internal_conn: Any,
+            close_only_if_idle: bool = True) -> None:
+        if internal_conn is None:
+            return
+        current = self._plugin_service.current_connection
+        driver_dialect = self._plugin_service.driver_dialect
+        if close_only_if_idle and internal_conn is current:
+            # In use and still usable (failover reconnected it) -> keep.
+            return
+        try:
+            if not await driver_dialect.is_closed(internal_conn):
+                result = internal_conn.close()
+                if asyncio.iscoroutine(result):
+                    await result
+        except Exception:  # noqa: BLE001 - cleanup is best-effort
+            pass
+        finally:
+            # Drop the cache slot so the dead connection is never reused.
+            if internal_conn is self._writer_conn:
+                self._writer_conn = None
+                if getattr(self, "_writer_host_info", None) is not None:
+                    self._writer_host_info = None
+            if internal_conn is self._reader_conn:
+                self._reader_conn = None
+                if getattr(self, "_reader_host_info", None) is not None:
+                    self._reader_host_info = None

aws_advanced_python_wrapper/aio/aiomysql.py

@@ -0,0 +1,68 @@
+#  Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
+#
+#  Licensed under the Apache License, Version 2.0 (the "License").
+#  You may not use this file except in compliance with the License.
+#  You may obtain a copy of the License at
+#
+#  http://www.apache.org/licenses/LICENSE-2.0
+#
+#  Unless required by applicable law or agreed to in writing, software
+#  distributed under the License is distributed on an "AS IS" BASIS,
+#  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+#  See the License for the specific language governing permissions and
+#  limitations under the License.
+
+"""PEP 249-style async DBAPI module bound to aiomysql.
+
+Async counterpart of :mod:`aws_advanced_python_wrapper.mysql_connector`.
+Enables SQLAlchemy's ``create_async_engine`` with the custom dialect
+``mysql+aws_wrapper_aiomysql``.
+
+Module-level attributes are populated via :func:`_dbapi.install`;
+PEP 562 ``__getattr__`` forwards missing attrs to the real
+:mod:`aiomysql` module so SA's MySQL-async dialect introspection keeps
+working.
+"""
+
+from __future__ import annotations
+
+import sys
+from typing import Any
+
+import aiomysql as _aiomysql
+
+from aws_advanced_python_wrapper import _dbapi
+from aws_advanced_python_wrapper.aio.wrapper import AsyncAwsWrapperConnection
+
+
+async def connect(conninfo: str = "", **kwargs: Any) -> AsyncAwsWrapperConnection:
+    """PEP 249 async ``connect``, target-driver-bound to aiomysql.
+
+    Equivalent to::
+
+        await AsyncAwsWrapperConnection.connect(
+            aiomysql.connect, conninfo, **kwargs)
+    """
+    return await AsyncAwsWrapperConnection.connect(
+        _aiomysql.connect, conninfo, **kwargs)
+
+
+def __getattr__(name: str) -> Any:
+    """Forward missing attributes to the underlying :mod:`aiomysql` module.
+
+    PEP 562 module-level ``__getattr__``. Fires only for names NOT
+    populated by :func:`_dbapi.install`, so PEP 249 exports take
+    precedence. SA's MySQL-aiomysql dialect probes the DBAPI module for
+    aiomysql-specific state (cursor class, error types, etc.);
+    forwarding lets it see the real driver.
+    """
+    try:
+        return getattr(_aiomysql, name)
+    except AttributeError:
+        raise AttributeError(
+            f"module 'aws_advanced_python_wrapper.aio.aiomysql' has no "
+            f"attribute {name!r}"
+        ) from None
+
+
+_dbapi.install(sys.modules[__name__].__dict__, connect=connect)