From 0b92a0abfbd759a295eb8d5ec80d9203486a0e46 Mon Sep 17 00:00:00 2001
From: Yurii Rashkovskii <yrashk@gmail.com>
Date: Fri, 15 Sep 2023 11:41:46 -0700
Subject: [PATCH v3] Improve ALTER ROLE documentation to document current
 behavior.

Previously, this was possible (assuming current_user is a bootstrap user):

```
ALTER ROLE current_user NOSUPERUSER
```

However, as of 16.0 this is no longer allowed:

```
ERROR:  permission denied to alter role
DETAIL:  The bootstrap user must have the SUPERUSER attribute.
```

Also, update the term across the board to use "bootstrap superuser"
---
 doc/src/sgml/glossary.sgml       | 3 ++-
 doc/src/sgml/ref/alter_role.sgml | 4 +++-
 doc/src/sgml/user-manag.sgml     | 2 +-
 src/backend/commands/user.c      | 2 +-
 4 files changed, 7 insertions(+), 4 deletions(-)

diff --git a/doc/src/sgml/glossary.sgml b/doc/src/sgml/glossary.sgml
index 5815fa4471..5839094fce 100644
--- a/doc/src/sgml/glossary.sgml
+++ b/doc/src/sgml/glossary.sgml
@@ -247,7 +247,8 @@
     </para>
     <para>
      This role also behaves as a normal
-     <glossterm linkend="glossary-database-superuser">database superuser</glossterm>.
+     <glossterm linkend="glossary-database-superuser">database superuser</glossterm>,
+     and its superuser status cannot be revoked.
     </para>
    </glossdef>
   </glossentry>
diff --git a/doc/src/sgml/ref/alter_role.sgml b/doc/src/sgml/ref/alter_role.sgml
index ab1ee45d54..361bae27c3 100644
--- a/doc/src/sgml/ref/alter_role.sgml
+++ b/doc/src/sgml/ref/alter_role.sgml
@@ -69,7 +69,9 @@ ALTER ROLE { <replaceable class="parameter">role_specification</replaceable> | A
    <link linkend="sql-grant"><command>GRANT</command></link> and
    <link linkend="sql-revoke"><command>REVOKE</command></link> for that.)
    Attributes not mentioned in the command retain their previous settings.
-   Database superusers can change any of these settings for any role.
+   Database superusers can change any of these settings for any role, except for
+   changing <literal>SUPERUSER</literal> to <literal>NOSUPERUSER</literal>
+   for the <glossterm linkend="glossary-bootstrap-superuser">bootstrap superuser</glossterm>.
    Non-superuser roles having <literal>CREATEROLE</literal> privilege can
    change most of these properties, but only for non-superuser and
    non-replication roles for which they have been granted
diff --git a/doc/src/sgml/user-manag.sgml b/doc/src/sgml/user-manag.sgml
index 92a299d2d3..1c011ac62b 100644
--- a/doc/src/sgml/user-manag.sgml
+++ b/doc/src/sgml/user-manag.sgml
@@ -350,7 +350,7 @@ ALTER ROLE myname SET enable_indexscan TO off;
    options. Thus, the fact that privileges are not inherited by default nor
    is <literal>SET ROLE</literal> granted by default is a safeguard against
    accidents, not a security feature. Also note that, because this automatic
-   grant is granted by the bootstrap user, it cannot be removed or changed by
+   grant is granted by the bootstrap superuser, it cannot be removed or changed by
    the <literal>CREATEROLE</literal> user; however, any superuser could
    revoke it, modify it, and/or issue additional such grants to other
    <literal>CREATEROLE</literal> users. Whichever <literal>CREATEROLE</literal>
diff --git a/src/backend/commands/user.c b/src/backend/commands/user.c
index 7e81589711..7a9c177b21 100644
--- a/src/backend/commands/user.c
+++ b/src/backend/commands/user.c
@@ -868,7 +868,7 @@ AlterRole(ParseState *pstate, AlterRoleStmt *stmt)
 			ereport(ERROR,
 					(errcode(ERRCODE_FEATURE_NOT_SUPPORTED),
 					 errmsg("permission denied to alter role"),
-					 errdetail("The bootstrap user must have the %s attribute.",
+					 errdetail("The bootstrap superuser must have the %s attribute.",
 							   "SUPERUSER")));
 
 		new_record[Anum_pg_authid_rolsuper - 1] = BoolGetDatum(should_be_super);
-- 
2.34.1