From 266d4d252af0da109d5ce69bf67b2170f449756c Mon Sep 17 00:00:00 2001
From: Nathan Bossart <bossartn@amazon.com>
Date: Thu, 11 Mar 2021 19:13:40 +0000
Subject: [PATCH v4 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       | 74 ++++++++++++++++++++++++++++++++++++++++++
 doc/src/sgml/ref/set_role.sgml | 13 ++++++--
 2 files changed, 84 insertions(+), 3 deletions(-)

diff --git a/doc/src/sgml/config.sgml b/doc/src/sgml/config.sgml
index a218d78bef..4b47268715 100644
--- a/doc/src/sgml/config.sgml
+++ b/doc/src/sgml/config.sgml
@@ -9139,6 +9139,80 @@ 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>.  It
+        cannot be set via the server configuration files, the server command
+        line, or
+        <link linkend="sql-altersystem"><command>ALTER SYSTEM</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>.
+        It cannot be set via the server configuration files, the server command
+        line, or
+        <link linkend="sql-altersystem"><command>ALTER SYSTEM</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..f02babf3af 100644
--- a/doc/src/sgml/ref/set_role.sgml
+++ b/doc/src/sgml/ref/set_role.sgml
@@ -53,9 +53,16 @@ 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.
+   <literal>SET ROLE NONE</literal> sets the current user identifier to the
+   current session user identifier, as returned by
+   <function>session_user</function>.  <literal>RESET ROLE</literal> sets the
+   current user identifier to the connection-time setting specified by the
+   <link linkend="libpq-connect-options">command-line options</link>,
+   <link linkend="sql-alterrole"><command>ALTER ROLE</command></link>, or
+   <link linkend="sql-alterdatabase"><command>ALTER DATABASE</command></link>,
+   if any such settings exist.  Otherwise, <literal>RESET ROLE</literal> sets
+   the current user identifier to the current session user identifier.  These
+   forms can be executed by any user.
   </para>
  </refsect1>
 
-- 
2.16.6