From f996ae88e1755995ef6db659c5cd6c33ec6f9e1d Mon Sep 17 00:00:00 2001
From: JackyHsu-X <xv1070733106@gmail.com>
Date: Wed, 28 Oct 2026 12:27:42 +0300
Subject: [PATCH] Clarify role reset for pooled connections

---
 asyncpg/connection.py |  8 +++++---
 asyncpg/pool.py       | 18 ++++++++++++++++++
 2 files changed, 23 insertions(+), 3 deletions(-)

diff --git a/asyncpg/connection.py b/asyncpg/connection.py
index c4067fc7..1d965c6e 100644
--- a/asyncpg/connection.py
+++ b/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
diff --git a/asyncpg/pool.py b/asyncpg/pool.py
index 29e9cb9d..c4d83d7b 100644
--- a/asyncpg/pool.py
+++ b/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.