Surface driver connection object when using a proxied dialect

Improve the interface used by adapted drivers, like the asyncio ones,
to access the actual connection object returned by the driver.

The :class:`_engine._ConnectionRecord` and
:class:`_engine._ConnectionFairy` now have two new attributes:

* ``dbapi_connection`` always represents a DBAPI compatible
object.  For pep-249 drivers, this is the DBAPI connection as it always
has been, previously accessed under the ``.connection`` attribute.
For asyncio drivers that SQLAlchemy adapts into a pep-249 interface,
the returned object will normally be a SQLAlchemy adaption object
called :class:`_engine.AdaptedConnection`.
* ``driver_connection`` always represents the actual connection object
maintained by the third party pep-249 DBAPI or async driver in use.
For standard pep-249 DBAPIs, this will always be the same object
as that of the ``dbapi_connection``.  For an asyncio driver, it will be
the underlying asyncio-only connection object.

The ``.connection`` attribute remains available and is now a legacy alias
of ``.dbapi_connection``.

Fixes: #6832
Change-Id: Ib72f97deefca96dce4e61e7c38ba430068d6a82e

3 files changed, 11 insertions, 7 deletions

diff --git a/lib/sqlalchemy/dialects/postgresql/asyncpg.py b/lib/sqlalchemy/dialects/postgresql/asyncpg.py
index 825558f26..dc3da224c 100644
--- a/lib/sqlalchemy/dialects/postgresql/asyncpg.py
+++ b/lib/sqlalchemy/dialects/postgresql/asyncpg.py
@@ -121,6 +121,7 @@ from ... import exc
 from ... import pool
 from ... import processors
 from ... import util
+from ...engine import AdaptedConnection
 from ...sql import sqltypes
 from ...util.concurrency import asyncio
 from ...util.concurrency import await_fallback
@@ -566,7 +567,7 @@ class AsyncAdapt_asyncpg_ss_cursor(AsyncAdapt_asyncpg_cursor):
         )
 
 
-class AsyncAdapt_asyncpg_connection:
+class AsyncAdapt_asyncpg_connection(AdaptedConnection):
     __slots__ = (
         "dbapi",
         "_connection",
@@ -1045,5 +1046,8 @@ class PGDialect_asyncpg(PGDialect):
 
         return connect
 
+    def get_driver_connection(self, connection):
+        return connection._connection
+
 
 dialect = PGDialect_asyncpg
diff --git a/lib/sqlalchemy/dialects/postgresql/pg8000.py b/lib/sqlalchemy/dialects/postgresql/pg8000.py
index 3d1051b7d..d42dd9560 100644
--- a/lib/sqlalchemy/dialects/postgresql/pg8000.py
+++ b/lib/sqlalchemy/dialects/postgresql/pg8000.py
@@ -433,8 +433,8 @@ class PGDialect_pg8000(PGDialect):
         level = level.replace("_", " ")
 
         # adjust for ConnectionFairy possibly being present
-        if hasattr(connection, "connection"):
-            connection = connection.connection
+        if hasattr(connection, "dbapi_connection"):
+            connection = connection.dbapi_connection
 
         if level == "AUTOCOMMIT":
             connection.autocommit = True
@@ -498,8 +498,8 @@ class PGDialect_pg8000(PGDialect):
 
     def set_client_encoding(self, connection, client_encoding):
         # adjust for ConnectionFairy possibly being present
-        if hasattr(connection, "connection"):
-            connection = connection.connection
+        if hasattr(connection, "dbapi_connection"):
+            connection = connection.dbapi_connection
 
         cursor = connection.cursor()
         cursor.execute("SET CLIENT_ENCODING TO '" + client_encoding + "'")
diff --git a/lib/sqlalchemy/dialects/postgresql/psycopg2.py b/lib/sqlalchemy/dialects/postgresql/psycopg2.py
index c80198825..a5a56cb6b 100644
--- a/lib/sqlalchemy/dialects/postgresql/psycopg2.py
+++ b/lib/sqlalchemy/dialects/postgresql/psycopg2.py
@@ -982,8 +982,8 @@ class PGDialect_psycopg2(PGDialect):
     @util.memoized_instancemethod
     def _hstore_oids(self, conn):
         extras = self._psycopg2_extras()
-        if hasattr(conn, "connection"):
-            conn = conn.connection
+        if hasattr(conn, "dbapi_connection"):
+            conn = conn.dbapi_connection
         oids = extras.HstoreAdapter.get_oids(conn)
         if oids is not None and oids[0]:
             return oids[0:2]