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

On Tue, Nov 01, 2022 at 03:47:15PM -0700, David G. Johnston wrote:
> Hey,
>
> Recent threads have pointed out some long-standing doc language in initdb
> that could be made more precise, especially in light of the relatively
> recent addition of a glossary. Toward this end I'm attaching a patch that
> defines three terms: "bootstrap superuser", "database superuser" and
> "superuser". I didn't add any extra-glossary links for the later two but
> did for the limited-in-scope bootstrap superuser that is really only
> defined in initdb (actually, I suspect the authorization docs could use a
> link too but haven't gone looking for an appropriate place yet).
>
> In passing I also changed a few places where the documentation says
> "database" when the thing being referred to is basically the file system
> data directory, which is a cluster-scoped thing.
>
> I did some grep'ing, though another pass or two is probably worthwhile.
> For now I submit a preliminary patch for consideration and buy-in before
> trying to polish it up.

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.

>+ 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

these comma

>+ 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

>+ <glossentry id="glossary-superuser">
>+ <glossterm>Superuser</glossterm>
>+ <glossdef>
>+ <para>
>+ As used in this documentation it is a synonym for

comma it

> Creating a database cluster consists of creating the directories in
>- which the database data will live, generating the shared catalog
>+ which the cluster data will live, generating the shared catalog

+1

> 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

> 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"

> <command>initdb</command>, but you can avoid writing it by
> setting the <envar>PGDATA</envar> environment variable, which
> can be convenient since the database server
>- (<command>postgres</command>) can find the database
>+ (<command>postgres</command>) can find the data
> directory later by the same variable.

+1

>- Makes <command>initdb</command> read the database superuser's password
>+ Makes <command>initdb</command> read the bootstrap superuser's password
> from a file. The first line of the file is taken as the password.

+1

>- Safely write all database files to disk and exit. This does not
>+ Safely write all database cluster files to disk and exit. This does not

+1

> It may be useful to adjust this size to control the granularity of
>- WAL log shipping or archiving. Also, in databases with a high volume
>+ WAL log shipping or archiving. Also, in clusters with a high volume
> of WAL, the sheer number of WAL files per directory can become a

+1