From f364779a4804754aff29112fb6d65762144f849b Mon Sep 17 00:00:00 2001
From: Nathan Bossart <bossartn@amazon.com>
Date: Wed, 10 Mar 2021 01:18:25 +0000
Subject: [PATCH v3 1/1] Small documentation fix for SET ROLE.

This change clarifies the behavior of RESET ROLE when "role" is set
per-user, per-database, or via command-line options.  Also, it adds
configuration parameter entries for "role" and
"session_authorization".
---
 doc/src/sgml/config.sgml       | 68 ++++++++++++++++++++++++++++++++++++++++++
 doc/src/sgml/ref/set_role.sgml | 10 +++++--
 2 files changed, 75 insertions(+), 3 deletions(-)

diff --git a/doc/src/sgml/config.sgml b/doc/src/sgml/config.sgml
index 529876895b..ffedd6cc14 100644
--- a/doc/src/sgml/config.sgml
+++ b/doc/src/sgml/config.sgml
@@ -9179,6 +9179,74 @@ SET XML OPTION { DOCUMENT | CONTENT };
     </variablelist>
    </sect2>
 
+   <sect2 id="runtime-config-identification">
+    <title>Identification</title>
+    <variablelist>
+
+     <varlistentry id="guc-role" xreflabel="role">
+      <term><varname>role</varname> (<type>string</type>)
+      <indexterm>
+       <primary><varname>role</varname> configuration parameter</primary>
+      </indexterm>
+      </term>
+      <listitem>
+       <para>
+        Sets the current user identifier.  See
+        <link linkend="sql-set-role"><command>SET ROLE</command></link> for more
+        information.
+       </para>
+       <para>
+        This parameter can be changed at connection-time via
+        <link linkend="libpq-connect-options">command-line options</link>,
+        <link linkend="sql-alterrole"><command>ALTER ROLE</command></link>, and
+        <link linkend="sql-alterdatabase"><command>ALTER DATABASE</command></link>
+        and at run-time via <link linkend="sql-set"><command>SET</command></link>
+        and <link linkend="sql-set-role"><command>SET ROLE</command></link>.
+       </para>
+       <note>
+        <para>
+         While connection-time settings for <varname>role</varname> modify a
+         session's default setting for <varname>role</varname>, such settings do
+         not affect other default settings for the session.  The originally
+         authenticated session user is used to determine other session defaults.
+        </para>
+       </note>
+      </listitem>
+     </varlistentry>
+
+     <varlistentry id="guc-session-authorization" xreflabel="session_authorization">
+      <term><varname>session_authorization</varname> (<type>string</type>)
+      <indexterm>
+       <primary><varname>session_authorization</varname> configuration parameter</primary>
+      </indexterm>
+      </term>
+      <listitem>
+       <para>
+        Sets the session user identifier and the current user identifier.  See
+        <link linkend="sql-set-session-authorization"><command>SET SESSION AUTHORIZATION</command></link>
+        for more information.
+       </para>
+       <para>
+        This parameter can only be changed at run-time via
+        <link linkend="sql-set"><command>SET</command></link> and
+        <link linkend="sql-set-session-authorization"><command>SET SESSION AUTHORIZATION</command></link>.
+       </para>
+       <note>
+        <para>
+         While it is possible to provide a connection-time setting for this
+         parameter via
+         <link linkend="libpq-connect-options">command-line options</link>,
+         <link linkend="sql-alterrole"><command>ALTER ROLE</command></link>, and
+         <link linkend="sql-alterdatabase"><command>ALTER DATABASE</command></link>,
+         such settings are silently ignored.
+        </para>
+       </note>
+      </listitem>
+     </varlistentry>
+
+    </variablelist>
+   </sect2>
+
      <sect2 id="runtime-config-client-other">
      <title>Other Defaults</title>
 
diff --git a/doc/src/sgml/ref/set_role.sgml b/doc/src/sgml/ref/set_role.sgml
index 739f2c5cdf..4eaec8d669 100644
--- a/doc/src/sgml/ref/set_role.sgml
+++ b/doc/src/sgml/ref/set_role.sgml
@@ -53,9 +53,13 @@ RESET ROLE
   </para>
 
   <para>
-   The <literal>NONE</literal> and <literal>RESET</literal> forms reset the current
-   user identifier to be the current session user identifier.
-   These forms can be executed by any user.
+   The <literal>NONE</literal> form resets the current user identifier to the
+   current session user identifier.  The <literal>RESET</literal> form resets
+   the current user identifier to the default value.  The default value can be
+   the command-line option value, the per-database default setting, or the
+   per-user default setting for the originally authenticated session user, if
+   any such settings exist.  Otherwise, the default value will be the current
+   session user identifier.  These forms can be executed by any user.
   </para>
  </refsect1>
 
-- 
2.16.6