add required subclass for async code

Signed-off-by: chrispy <chrispy@synopsys.com>

diff --git a/lib/sqlalchemy/dialects/postgresql/psycopg.py b/lib/sqlalchemy/dialects/postgresql/psycopg.py
index d41bdae7e7ab449b3f6bc3efea995843ab32b2af..60ee8e98e26755b430638a9ca360a62ac27bf178 100644 (file)
--- a/lib/sqlalchemy/dialects/postgresql/psycopg.py
+++ b/lib/sqlalchemy/dialects/postgresql/psycopg.py
@@ -74,7 +74,7 @@ for both synchronous and asynchronous code environments.
 
 To take advantage of ``psycopg``'s pool,
 
-- Create a custom ``psycopg.Connection`` class that returns "closed"
+- Create a custom ``psycopg.Connection`` subclass that returns "closed"
   checked-out pool connections to the pool.
 - Create a ``psycopg_pool.ConnectionPool`` instance that uses this connection
   class along with the desired pool configuration.
@@ -85,7 +85,7 @@ To take advantage of ``psycopg``'s pool,
   - Sets the ``create_engine.creator`` parameter to use the Psycopg 3 pool to
     obtain new connections.
 
-For example::
+Here is an example that uses ``psycopg_pool.ConnectionPool``::
 
     import psycopg
     import psycopg_pool
@@ -117,6 +117,20 @@ For example::
         creator=mypool.getconn,       # Use Psycopg 3 connection pool to obtain connections
     )
 
+Usage of ``psycopg_pool.AsyncConnectionPool`` is similar, but it requires the
+following ``psycopg.AsyncConnection`` subclass instead:
+
+    class MyConnection(psycopg.AsyncConnection):
+        async def close(self):
+            if pool := getattr(self, "_pool", None):
+                # Connection currently checked out from its pool;
+                # instead of closing it, return it to the pool.
+                await pool.putconn(self)
+            else:
+                # Connection being removed from its pool, or not part of any pool;
+                # close the connection for real.
+                await super().close()
+
 The resulting engine may then be used normally. Internally, Psycopg 3 handles
 connection pooling::