On Fri, 2021-03-12 at 10:16 +0100, I wrote:
> After sleeping on it, I have come to think that it is excessive to write
> so much documentation for a feature that is that unimportant.
>
> It takes some effort to come up with a good use case for it.
>
> I think we can add a few lines to ALTER ROLE, perhaps ALTER DATABASE
> (although I don't see what sense it could make to set that on the database
> level),
> and briefly explain the difference between RESET ROLE and SET ROLE NONE.
>
> I think adding too much detail will harm - anyone who needs to know the
> exact truth can resort to the implementation.
>
> I'll try to come up with a proposal later.
Attached is my idea of the documentation change.
I think that ALTER DATABASE ... SET ROLE can remain undocumented, because
I cannot imagine that it could be useful.
I am unsure if specifying "role" in a libpq connect string might be
worth documenting. Can you think of a use case?
Yours,
Laurenz Albe
From 5daa6c2a874898506fda316fe651f107dbed34d5 Mon Sep 17 00:00:00 2001
From: Laurenz Albe <laurenz.a...@cybertec.at>
Date: Fri, 12 Mar 2021 15:32:01 +0100
Subject: [PATCH] Document ALTER ROLE ... SET ROLE
This was previously undocumented, like ALTER DATABASE ... SET ROLE or
specifying "role=some_role" in a libpq connect string, but it might
have some practical use cases.
---
doc/src/sgml/ref/alter_role.sgml | 15 +++++++++++++--
doc/src/sgml/ref/set_role.sgml | 8 ++++++--
2 files changed, 19 insertions(+), 4 deletions(-)
diff --git a/doc/src/sgml/ref/alter_role.sgml b/doc/src/sgml/ref/alter_role.sgml
index 5aa5648ae7..a377fc303b 100644
--- a/doc/src/sgml/ref/alter_role.sgml
+++ b/doc/src/sgml/ref/alter_role.sgml
@@ -40,6 +40,7 @@ ALTER ROLE <replaceable class="parameter">name</replaceable> RENAME TO <replacea
ALTER ROLE { <replaceable class="parameter">role_specification</replaceable> | ALL } [ IN DATABASE <replaceable class="parameter">database_name</replaceable> ] SET <replaceable>configuration_parameter</replaceable> { TO | = } { <replaceable>value</replaceable> | DEFAULT }
ALTER ROLE { <replaceable class="parameter">role_specification</replaceable> | ALL } [ IN DATABASE <replaceable class="parameter">database_name</replaceable> ] SET <replaceable>configuration_parameter</replaceable> FROM CURRENT
+ALTER ROLE { <replaceable class="parameter">role_specification</replaceable> | ALL } [ IN DATABASE <replaceable class="parameter">database_name</replaceable> ] SET ROLE <replaceable class="parameter">other_role</replaceable>
ALTER ROLE { <replaceable class="parameter">role_specification</replaceable> | ALL } [ IN DATABASE <replaceable class="parameter">database_name</replaceable> ] RESET <replaceable>configuration_parameter</replaceable>
ALTER ROLE { <replaceable class="parameter">role_specification</replaceable> | ALL } [ IN DATABASE <replaceable class="parameter">database_name</replaceable> ] RESET ALL
@@ -91,7 +92,7 @@ ALTER ROLE { <replaceable class="parameter">role_specification</replaceable> | A
<para>
The remaining variants change a role's session default for a configuration
- variable, either for all databases or, when the <literal>IN
+ variable or the role assumed, either for all databases or, when the <literal>IN
DATABASE</literal> clause is specified, only for sessions in the named
database. If <literal>ALL</literal> is specified instead of a role name,
this changes the setting for all roles. Using <literal>ALL</literal>
@@ -104,7 +105,7 @@ ALTER ROLE { <replaceable class="parameter">role_specification</replaceable> | A
starts a new session, the specified value becomes the session
default, overriding whatever setting is present in
<filename>postgresql.conf</filename> or has been received from the <command>postgres</command>
- command line. This only happens at login time; executing
+ command line. This only happens at login time; executing
<link linkend="sql-set-role"><command>SET ROLE</command></link> or
<link linkend="sql-set-session-authorization"><command>SET SESSION AUTHORIZATION</command></link> does not cause new
configuration values to be set.
@@ -234,6 +235,16 @@ ALTER ROLE { <replaceable class="parameter">role_specification</replaceable> | A
</para>
</listitem>
</varlistentry>
+
+ <varlistentry>
+ <term><replaceable>other_role</replaceable></term>
+ <listitem>
+ <para>
+ The name of a role that contains the modified role as a member.
+ This identity is automatically assumed when the connection is established.
+ </para>
+ </listitem>
+ </varlistentry>
</variablelist>
</refsect1>
diff --git a/doc/src/sgml/ref/set_role.sgml b/doc/src/sgml/ref/set_role.sgml
index 739f2c5cdf..4ce4873fe8 100644
--- a/doc/src/sgml/ref/set_role.sgml
+++ b/doc/src/sgml/ref/set_role.sgml
@@ -53,8 +53,12 @@ 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.
+ <literal>SET ROLE NONE</literal> sets the current user identifier to the
+ session user identifier, as returned by <function>session_user</function>.
+ <literal>RESET ROLE</literal> sets the current user identifier to the
+ connection-time setting, which may be different from the session user
+ identifier if a different role has been set with
+ <link linkend="sql-alterrole"><command>ALTER ROLE</command></link>.
These forms can be executed by any user.
</para>
</refsect1>
--
2.26.2
