docs: clarify role reset for pooled connections

asyncpg/connection.py

@@ -1571,9 +1571,11 @@ async def reset(self, *, timeout=None):
         resembling that of a newly obtained connection.  Namely, an open
         transaction (if any) is rolled back, open cursors are closed,
         all `LISTEN <https://www.postgresql.org/docs/current/sql-listen.html>`_
-        registrations are removed, all session configuration
-        variables are reset to their default values, and all advisory locks
-        are released.
+        registrations are removed, session configuration variables covered by
+        ``RESET ALL`` are reset to their default values, and all advisory locks
+        are released.  This does not reset all session state: for example,
+        a session-level ``SET ROLE`` is not undone by ``RESET ALL``.  Use
+        ``RESET ROLE`` explicitly if the role also needs to be reset.
 
         Note that the above describes the default query returned by
         :meth:`Connection.get_reset_query`.  If one overloads the method

asyncpg/pool.py

@@ -1336,6 +1336,24 @@ def create_pool(dsn=None, *,
         by calling :meth:`Connection.get_reset_query() <\
         asyncpg.connection.Connection.get_reset_query>`.
 
+        The default reset does not undo a session-level ``SET ROLE``.
+        Applications that change roles must reset the role explicitly if it
+        should not be retained by the next acquirer.  For example, to keep
+        the default cleanup and also reset the role::
+
+            async def reset_connection(conn):
+                await conn.reset()
+                await conn.execute('RESET ROLE')
+
+            pool = await asyncpg.create_pool(..., reset=reset_connection)
+
+        Calling ``conn.reset()`` first also rolls back any open transaction,
+        so ``RESET ROLE`` can run even if the transaction was left aborted.
+        ``RESET ROLE`` restores the connection-time role setting, or the
+        session user if no such setting exists.
+        If a role must be applied on every acquisition, use *setup* rather
+        than *init*, which only runs when a connection is created.
+
     :param loop:
         An asyncio event loop instance.  If ``None``, the default
         event loop will be used.