doc: Add note about "Client User" and "Superuser" fields in \conninfo output.

In the \conninfo psql command, the "Client User" column shows the user who
established the connection, while the "Superuser" column reflects whether
the current user in the current execution context is a superuser. This means
the users referred to in these columns can differ, for example, if the current
user was changed with the SET ROLE command.

This commit adds a note to the \conninfo documentation to clarify
this behavior and avoid potential confusion.

Author: Fujii Masao <masao.fujii@gmail.com>
Reviewed-by: Robert Treat <rob@xzilla.net>
Reviewed-by: David G. Johnston <david.g.johnston@gmail.com>
Discussion: https://postgr.es/m/685961b8-b6ce-40bb-b2d5-c2ff135d3388@oss.nttdata.com

diff --git a/doc/src/sgml/ref/psql-ref.sgml b/doc/src/sgml/ref/psql-ref.sgml
index a7fd4a21d9f92ea3e70de4be34f83df9e76dbce0..15e3f3a849226bc1218a5e7cd147dd7819283e86 100644 (file)
--- a/doc/src/sgml/ref/psql-ref.sgml
+++ b/doc/src/sgml/ref/psql-ref.sgml
@@ -1103,6 +1103,15 @@ SELECT $1 \parse stmt1
           Outputs information about the current database connection,
           including TLS-related information if TLS is in use.
          </para>
+         <para>
+          Note that the <structfield>Client User</structfield> field shows
+          the user at the time of connection, while the
+          <structfield>Superuser</structfield> field indicates whether
+          the current user (in the current execution context) has
+          superuser privileges. These users are usually the same, but they can
+          differ, for example, if the current user was changed with the
+          <command>SET ROLE</command> command.
+         </para>
         </listitem>
       </varlistentry>