MIME-Version: 1.0
References: <ZmtM-4-eRtq8DRf6@nathan> <CA+TgmoYhyieAwqvGYRTdz92ySFCScjsPLh_KySZohtWBfW-Usg@mail.gmail.com>
 <ZnG7PNN6BK32G_6B@nathan> <CAKFQuwZTGgQs1TB=yxHhBAkLK1HCeiQkZnxR=gYi9sqw1bB-ng@mail.gmail.com>
 <ZnWe3RgnCV4RR9KB@nathan>
In-Reply-To: <ZnWe3RgnCV4RR9KB@nathan>
From: Robert Haas <robertmhaas@gmail.com>
Date: Mon, 24 Jun 2024 14:44:33 -0400
Message-ID: <CA+TgmobSbh2eLHPXi-eTmGy80f6Wq72eDef_sDcpB2-8RBi6OQ@mail.gmail.com>
Subject: Re: improve predefined roles documentation
To: Nathan Bossart <nathandbossart@gmail.com>
Cc: "David G. Johnston" <david.g.johnston@gmail.com>, pgsql-hackers@postgresql.org
Content-Type: text/plain; charset="UTF-8"
Content-Transfer-Encoding: quoted-printable
Archived-At: <https://www.postgresql.org/message-id/CA%2BTgmobSbh2eLHPXi-eTmGy80f6Wq72eDef_sDcpB2-8RBi6OQ%40mail.gmail.com>
Precedence: bulk

On Fri, Jun 21, 2024 at 11:40=E2=80=AFAM Nathan Bossart
<nathandbossart@gmail.com> wrote:
> Done.

If you look at how the varlistentries begin, there are three separate patte=
rns:

* Some document a single role and start with "Allow doing blah blah blah".

* Some document a couple of rolls so there are several paragraphs,
each beginning with "<literal>name_of_role</literal allows doing blah
blah blah". This is sometimes preceded by an introductory paragraph
explaining why this group of roles exists and what it's intended to
do.

* pg_database_owner is completely different from the rest, focusing on
explaining who is in the role rather than what the role gets to do.

I think the first two cases could be made more like each other by
changing the varlistentires that are just about one setting to use the
second format instead of the first, e.g. pg_checkpoint allows
executing the CHECKPOINT command.

I don't know what to do about pg_database_owner. I almost wonder if
that should be moved out of the table and documented as a special
case. Or maybe some more wordsmithing would add clarity. Or maybe it's
fine as-is.

--=20
Robert Haas
EDB: http://www.enterprisedb.com