Switch the default async Postgres driver from asyncpg to psycopg3 (provider)

providers/postgres/README.rst

@@ -58,7 +58,8 @@ PIP package                                 Version required
 ``apache-airflow-providers-common-sql``     ``>=1.32.0``
 ``psycopg2-binary``                         ``>=2.9.9; python_version < "3.13"``
 ``psycopg2-binary``                         ``>=2.9.10; python_version >= "3.13"``
-``asyncpg``                                 ``>=0.30.0``
+``psycopg[binary]``                         ``>=3.2.9; python_version < "3.14"``
+``psycopg[binary]``                         ``>=3.3.3; python_version >= "3.14"``
 ==========================================  ======================================
 
 Optional cross provider package dependencies
@@ -89,11 +90,11 @@ Optional dependencies
 Extra                Dependencies
 ===================  ============================================================================================================================================================
 ``amazon``           ``apache-airflow-providers-amazon>=2.6.0``
+``asyncpg``          ``asyncpg>=0.30.0``
 ``microsoft.azure``  ``apache-airflow-providers-microsoft-azure>=12.8.0``
 ``openlineage``      ``apache-airflow-providers-openlineage``
 ``pandas``           ``pandas>=2.1.2; python_version <"3.13"``, ``pandas>=2.2.3; python_version >="3.13" and python_version <"3.14"``, ``pandas>=2.3.3; python_version >="3.14"``
 ``polars``           ``polars>=1.26.0``
-``psycopg``          ``psycopg[binary]>=3.2.9; python_version < '3.14'``, ``psycopg[binary]>=3.3.3; python_version >= '3.14'``
 ``sqlalchemy``       ``sqlalchemy>=1.4.54``
 ===================  ============================================================================================================================================================
 

providers/postgres/docs/changelog.rst

@@ -27,6 +27,21 @@
 Changelog
 ---------
 
+
+Breaking changes
+~~~~~~~~~~~~~~~~
+
+.. note::
+    The default async metadata-database driver is now ``psycopg`` (psycopg3),
+    which is installed by default in place of ``asyncpg``. As a result, the
+    ``[psycopg]`` optional extra was removed and ``[asyncpg]`` was added.
+
+    Starting with Airflow 3.4.0, the default derived async connection URL changes from
+    ``postgresql+asyncpg://`` to ``postgresql+psycopg_async://``, which is safe behind
+    transaction-mode PgBouncer with no extra configuration. To keep using asyncpg, install
+    ``apache-airflow-providers-postgres[asyncpg]`` and set
+    ``[database] sql_alchemy_conn_async = postgresql+asyncpg://...`` explicitly.
+
 6.8.0
 .....
 

providers/postgres/docs/index.rst

@@ -106,7 +106,8 @@ PIP package                                 Version required
 ``apache-airflow-providers-common-sql``     ``>=1.32.0``
 ``psycopg2-binary``                         ``>=2.9.9; python_version < "3.13"``
 ``psycopg2-binary``                         ``>=2.9.10; python_version >= "3.13"``
-``asyncpg``                                 ``>=0.30.0``
+``psycopg[binary]``                         ``>=3.2.9; python_version < "3.14"``
+``psycopg[binary]``                         ``>=3.3.3; python_version >= "3.14"``
 ==========================================  ======================================
 
 Optional cross provider package dependencies

providers/postgres/pyproject.toml

@@ -62,9 +62,12 @@ dependencies = [
     "apache-airflow>=2.11.0",
     "apache-airflow-providers-common-compat>=1.12.0",
     "apache-airflow-providers-common-sql>=1.32.0",
+    # psycopg2 remains the sync driver for now; its removal and the sync migration to
+    # psycopg3 are tracked at https://github.com/apache/airflow/issues/68453
     "psycopg2-binary>=2.9.9; python_version < '3.13'",
     "psycopg2-binary>=2.9.10; python_version >= '3.13'",
-    "asyncpg>=0.30.0",
+    "psycopg[binary]>=3.2.9; python_version < '3.14'",
+    "psycopg[binary]>=3.3.3; python_version >= '3.14'",
 ]
 
 # The optional dependencies should be modified in place in the generated file
@@ -73,6 +76,9 @@ dependencies = [
 "amazon" = [
     "apache-airflow-providers-amazon>=2.6.0",
 ]
+"asyncpg" = [
+    "asyncpg>=0.30.0",
+]
 "microsoft.azure" = [
     "apache-airflow-providers-microsoft-azure>=12.8.0"
 ]
@@ -87,10 +93,6 @@ dependencies = [
 "polars" = [
     "polars>=1.26.0"
 ]
-"psycopg" = [
-    "psycopg[binary]>=3.2.9; python_version < '3.14'",
-    "psycopg[binary]>=3.3.3; python_version >= '3.14'",
-]
 "sqlalchemy" = [
     "sqlalchemy>=1.4.54"
 ]
@@ -108,6 +110,7 @@ dev = [
     # Additional devel dependencies (do not remove this line and add extra development dependencies)
     "apache-airflow-providers-common-sql[pandas]",
     "apache-airflow-providers-common-sql[polars]",
+    "apache-airflow-providers-postgres[asyncpg]",
     "apache-airflow-providers-postgres[sqlalchemy]"
 ]
 

providers/postgres/src/airflow/providers/postgres/hooks/postgres.py

@@ -70,30 +70,14 @@
 
 
 class CompatConnection(Protocol):
-    """Protocol for type hinting psycopg2 and psycopg3 connection objects."""
+    """Protocol for the common interface shared by psycopg2 and psycopg3 connection objects."""
 
     def cursor(self, *args, **kwargs) -> Any: ...
     def commit(self) -> None: ...
     def close(self) -> None: ...
-
-    # Context manager support
-    def __enter__(self) -> CompatConnection: ...
+    def __enter__(self) -> Any: ...
     def __exit__(self, exc_type: Any, exc_val: Any, exc_tb: Any) -> None: ...
 
-    # Common properties
-    @property
-    def notices(self) -> list[Any]: ...
-
-    # psycopg3 specific (optional)
-    @property
-    def adapters(self) -> Any: ...
-
-    @property
-    def row_factory(self) -> Any: ...
-
-    # Optional method for psycopg3
-    def add_notice_handler(self, handler: Any) -> None: ...
-
 
 class PostgresHook(DbApiHook):
     """