From 6eefe2ce463f55bb3b8da7d561ad2f75053189e0 Mon Sep 17 00:00:00 2001
From: Tom Lane
Date: Sun, 26 Mar 2023 14:48:04 -0400
Subject: Doc: clarify introduction to database roles.

Word-smith section 22.1 ("Database Roles") a little bit in hopes
of removing confusion about how the bootstrap superuser's name
is chosen.

While here, I couldn't help noticing that the claim that the bootstrap
superuser is the only initially-existing role has been a lie since
we started to invent predefined roles.  We don't want too much detail
in this very introductory text, but it seems worth changing it to say
that it's the only initially-existing login-capable role.

Per documentation comment from Maja Zaloznik.

Discussion: https://postgr.es/m/167931662853.3349090.18217722739345182859@wrigleys.postgresql.org
---
 doc/src/sgml/user-manag.sgml | 17 +++++++++++------
 1 file changed, 11 insertions(+), 6 deletions(-)

(limited to 'doc/src')

diff --git a/doc/src/sgml/user-manag.sgml b/doc/src/sgml/user-manag.sgml
index 93978e550e..d99dcb2017 100644
--- a/doc/src/sgml/user-manag.sgml
+++ b/doc/src/sgml/user-manag.sgml
@@ -88,9 +88,13 @@ dropuser <replaceable>name</replaceable>
 
   <para>
    To determine the set of existing roles, examine the <structname>pg_roles</structname>
-   system catalog, for example
+   system catalog, for example:
 <synopsis>
 SELECT rolname FROM pg_roles;
+</synopsis>
+   or to see just those capable of logging in:
+<synopsis>
+SELECT rolname FROM pg_roles WHERE rolcanlogin;
 </synopsis>
    The <xref linkend="app-psql"/> program's <literal>\du</literal> meta-command
    is also useful for listing the existing roles.
@@ -98,11 +102,12 @@ SELECT rolname FROM pg_roles;
 
   <para>
    In order to bootstrap the database system, a freshly initialized
-   system always contains one predefined role. This role is always
-   a <quote>superuser</quote>, and by default (unless altered when running
-   <command>initdb</command>) it will have the same name as the
-   operating system user that initialized the database
-   cluster. Customarily, this role will be named
+   system always contains one predefined login-capable role. This role
+   is always a <quote>superuser</quote>, and by default it will have
+   the same name as the operating system user that initialized the
+   database cluster, unless another name is specified while
+   running <command>initdb</command>.
+   It is common, but not required, to arrange for this role to be named
    <literal>postgres</literal>. In order to create more roles you
    first have to connect as this initial role.
   </para>
-- 
cgit v1.2.3