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
