Re: Glossary and initdb definition work for "superuser" and database/cluster - Mailing list pgsql-hackers

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