From c26916e523dd7fd8381de0a16445c02bf27e2972 Mon Sep 17 00:00:00 2001
From: Nathan Bossart <bossartn@amazon.com>
Date: Thu, 11 Mar 2021 22:18:30 +0000
Subject: [PATCH v5 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
additional information about setting "role" in these ways.
---
 doc/src/sgml/libpq.sgml              | 12 ++++++++++++
 doc/src/sgml/ref/alter_database.sgml | 10 ++++++++++
 doc/src/sgml/ref/alter_role.sgml     | 10 ++++++++++
 doc/src/sgml/ref/set.sgml            | 22 ++++++++++++++++++++++
 doc/src/sgml/ref/set_role.sgml       | 13 ++++++++++---
 5 files changed, 64 insertions(+), 3 deletions(-)

diff --git a/doc/src/sgml/libpq.sgml b/doc/src/sgml/libpq.sgml
index 910e9a81ea..6d0539a18c 100644
--- a/doc/src/sgml/libpq.sgml
+++ b/doc/src/sgml/libpq.sgml
@@ -1288,6 +1288,18 @@ postgresql://%2Fvar%2Flib%2Fpostgresql/dbname
         backslash.  For a detailed discussion of the available
         options, consult <xref linkend="runtime-config"/>.
        </para>
+       <note>
+        <para>
+         In addition to the options listed in <xref linkend="runtime-config"/>,
+         <varname>role</varname> may be used as a command-line option.  While
+         setting <varname>role</varname> via command-line options modifies its
+         default setting for the session, such settings will not affect other
+         default settings for the session.  The originally authenticated session
+         user is used to determine other session defaults.  See 
+         <link linkend="sql-set-role"><command>SET ROLE</command></link> for
+         more information.
+        </para>
+       </note>
       </listitem>
      </varlistentry>
 
diff --git a/doc/src/sgml/ref/alter_database.sgml b/doc/src/sgml/ref/alter_database.sgml
index 81e37536a3..67e5a4b5f0 100644
--- a/doc/src/sgml/ref/alter_database.sgml
+++ b/doc/src/sgml/ref/alter_database.sgml
@@ -187,6 +187,16 @@ ALTER DATABASE <replaceable class="parameter">name</replaceable> RESET ALL
         the parameter as the database-specific value.
        </para>
 
+       <para>
+        <varname>role</varname> may be used as a configuration parameter in this
+        command.  While database-specific settings for <varname>role</varname>
+        modify its default setting for new sessions, such settings do not affect
+        other default settings for the session.  The originally authenticated
+        session user is used to determine other session defaults.  See
+        <link linkend="sql-set-role"><command>SET ROLE</command></link> for more
+        information.
+       </para>
+
        <para>
         See <xref linkend="sql-set"/> and <xref linkend="runtime-config"/>
         for more information about allowed parameter names
diff --git a/doc/src/sgml/ref/alter_role.sgml b/doc/src/sgml/ref/alter_role.sgml
index 5aa5648ae7..5c4651e190 100644
--- a/doc/src/sgml/ref/alter_role.sgml
+++ b/doc/src/sgml/ref/alter_role.sgml
@@ -220,6 +220,16 @@ ALTER ROLE { <replaceable class="parameter">role_specification</replaceable> | A
         parameter is set or removed for the given role and database only.
        </para>
 
+       <para>
+        <varname>role</varname> may be used as a configuration parameter in this
+        command.  While role-specific settings for <varname>role</varname>
+        modify its default setting for new sessions, such settings do not affect
+        other default settings for the session.  The originally authenticated
+        session user is used to determine other session defaults.  See
+        <link linkend="sql-set-role"><command>SET ROLE</command></link> for more
+        information.
+       </para>
+
        <para>
         Role-specific variable settings take effect only at login;
         <link linkend="sql-set-role"><command>SET ROLE</command></link> and
diff --git a/doc/src/sgml/ref/set.sgml b/doc/src/sgml/ref/set.sgml
index 339ee9eec9..631522e22c 100644
--- a/doc/src/sgml/ref/set.sgml
+++ b/doc/src/sgml/ref/set.sgml
@@ -258,6 +258,28 @@ SELECT setseed(<replaceable>value</replaceable>);
       </para>
      </listitem>
     </varlistentry>
+
+    <varlistentry>
+     <term><literal>role</literal></term>
+     <listitem>
+      <para>
+       <literal>SET role TO <replaceable>value</replaceable></literal> is an
+       alias for
+       <link linkend="sql-set-role"><command>SET ROLE</command></link>.
+      </para>
+     </listitem>
+    </varlistentry>
+
+    <varlistentry>
+     <term><literal>session_authorization</literal></term>
+     <listitem>
+      <para>
+       <literal>SET session_authorization TO <replaceable>value</replaceable></literal>
+       is an alias for
+       <link linkend="sql-set-session-authorization"><command>SET SESSION AUTHORIZATION</command></link>.
+      </para>
+     </listitem>
+    </varlistentry>
    </variablelist>
   </para>
  </refsect1>
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