[JackyHsu-X]

Problem

Connection.reset() currently says that all session configuration variables are reset. However, the default query uses RESET ALL, which does not undo a committed session-level SET ROLE. Releasing a connection to a pool can therefore leave its role in effect for the next acquirer.

Related to #1402. This addresses the documentation option in that issue; it leaves the decision about changing the default reset behavior open.

Change

• Describe the reset scope in terms of RESET ALL rather than every session variable.
• Show a custom pool reset callback that calls conn.reset() before RESET ROLE, preserving default cleanup and handling an aborted transaction.
• Explain that RESET ROLE restores a connection-time role setting when present, and that a role needed on each acquisition belongs in setup, rather than init.

Only two API docstrings change; executable Python ASTs are unchanged.

Validation

• Executed the callback extracted from the edited docstring against asyncpg 0.32.0 / PostgreSQL 18.6, using a one-connection pool. Confirmed the default reset retains the role on the same backend, whereas the callback restores the role and ordinary settings.
• Verified recovery from an aborted transaction, preservation of a connection-time role supplied through server_settings, and init once versus setup on both acquisitions.
• Generated the full Sphinx HTML documentation with nitpicky warnings treated as errors. Both the unchanged and edited docstrings produce the same 51 existing unresolved-reference warnings; no new warnings. This is not a clean strict build. Used the installed release's native extensions and loaded the edited docstrings from the source AST; did not compile a development extension.
• git diff --check passes. Full runtime tests were not run for this documentation-only change.

PostgreSQL documents the connection-time behavior of RESET ROLE in SET ROLE.

AI disclosure: OpenAI Codex prepared the patch, example verification and PR text, and ran the listed checks. This does not claim human review by the account owner.