Re: Glossary and initdb definition work for "superuser" and database/cluster

On Tue, Nov 1, 2022 at 5:20 PM Justin Pryzby <pryzby(at)telsasoft(dot)com> wrote:

> On Tue, Nov 01, 2022 at 03:47:15PM -0700, David G. Johnston wrote:
>
>
> I think this is wrong:
>
> | https://www.postgresql.org/docs/devel/app-initdb.html
> | -U username
> | --username=username
> |
> | Selects the user name of the database superuser. This defaults to
> | the name of the effective user running initdb [...]
>
> It's true that the user who runs initdb is typically named "postgres",
> but that's only by convention.
>

Thanks. I feel bad for missing this one given that I've been working on
fixing up the default libpq user name wording.

>
> >+ This user owns all system catalog tables in each database. It also
> is the role
> >+ from which all granted permission originate. Because of these
> things this
> >+ role may not be dropped.
>
> plural permissions
>
+1

>
> these comma
>

things comma actually (+0.5)

> >+ While the <glossterm
> linkend="glossary-bootstrap-superuser">bootstrap superuser</glossterm> is
> >+ a database superuser it has special obligations and restrictions
> that plain database superusers do not.
>
> comma it
>

+ 0.5

>
> > tables (tables that belong to the whole cluster rather than to any
> >- particular database), and creating the <literal>postgres</literal>,
> >- <literal>template1</literal>, and <literal>template0</literal>
> databases.
> >+ particular database), creating the <literal>postgres</literal>,
> >+ <literal>template1</literal>, and <literal>template0</literal>
> databases,
> >+ and creating the
> >+ <glossterm linkend="glossary-bootstrap-superuser">boostrap
> superuser</glossterm>
> >+ (<literal>postgres</literal>, by default).
>
> "postgres" is wrong
>

Yep, will give this another look to see if anywhere but the actual option
description wants to cover how this really works (or maybe just point the
reader there).

> > For security reasons the new cluster created by
> <command>initdb</command>
> >- will only be accessible by the cluster owner by default. The
> >+ will only be accessible by the cluster user by default. The
>
> I prefer "cluster owner"
>

I'll either need to change it back or fix the one in the next sentence...

I'm still leaning toward continuing to use cluster user like everywhere
else on the page instead of adding a new term. The fact that this doesn't
work on Windows makes having it in the description section at all
arguable. I'd rather rewrite it something like:

"On POSIX systems, the resulting data directory, and all of its contents,
will have permissions of 700, though you can use --allow-group-access to
instead get 750. In either case, the effective user running initdb will
become the owner and group for the files created within the data directory."

(I haven't tried to prove this owner:group dynamic, but having 700 or 750
and specifying the alternative does result in the directory having its
permission bits changed during initdb)

Feel free to suggest something if similar wording should be added for
non-POSIX systems.

I intend to try and integrate something like the above to replace the
existing paragraph in the next version.

Thank you for the review!

David J.

P.S. I'm now looking at the very first paragraph to initdb more closely,
not liking "single server instance" all that much and wondering how to fit
in "cluster user" there - possibly by saying something like "...managed by
a single server process, and physical data directory, whose effective user
and owner respectively is called the cluster user. That user must exist
and be used to execute this program."

Then the whole "initdb must be run as..." paragraph can probably just go
away. Moving the commentary about "root", again a non-Windows thing, to
the notes area.