Add glossary entries related to superusers

Extracted from a more ambitious patch.

Author: David G. Johnston <david.g.johnston@gmail.com>
Discussion: https://postgr.es/m/CAKFQuwZC4K0XYBm0bwBMDOZySBqhOSekDhLuaw4vPi+ozi8gqQ@mail.gmail.com

diff --git a/doc/src/sgml/adminpack.sgml b/doc/src/sgml/adminpack.sgml
index 1150b7f5bbedb664d50ddf41ecb621193d8f84e5..184e96d7a0c5e528c558579205aff5e7f6fd3461 100644 (file)
--- a/doc/src/sgml/adminpack.sgml
+++ b/doc/src/sgml/adminpack.sgml
@@ -12,7 +12,7 @@
   <application>pgAdmin</application> and other administration and management tools can
   use to provide additional functionality, such as remote management
   of server log files.
-  Use of all these functions is only allowed to the superuser by default but may be
+  Use of all these functions is only allowed to database superusers by default, but may be
   allowed to other users by using the <command>GRANT</command> command.
  </para>
 

diff --git a/doc/src/sgml/glossary.sgml b/doc/src/sgml/glossary.sgml
index d6d0a3a8140cddf0d800ff773ad783cc62f79d55..93fb149d9a26299f18d79dd5c6a8907301fdb631 100644 (file)
--- a/doc/src/sgml/glossary.sgml
+++ b/doc/src/sgml/glossary.sgml
@@ -233,6 +233,25 @@
    </glossdef>
   </glossentry>
 
+  <glossentry id="glossary-bootstrap-superuser">
+   <glossterm>Bootstrap superuser</glossterm>
+   <glossdef>
+    <para>
+     The first <glossterm linkend="glossary-user">user</glossterm> initialized in a
+     <glossterm linkend="glossary-db-cluster">database cluster</glossterm>.
+    </para>
+    <para>
+     This user owns all system catalog tables in each database.  It is also the role
+     from which all granted permissions originate.  Because of these things, this
+     role may not be dropped.
+    </para>
+    <para>
+     This role also behaves as a normal
+     <glossterm linkend="glossary-database-superuser">database superuser</glossterm>.
+    </para>
+   </glossdef>
+  </glossentry>
+
   <glossentry id="glossary-cast">
    <glossterm>Cast</glossterm>
    <glossdef>
@@ -342,6 +361,23 @@
    </glossdef>
   </glossentry>
 
+  <glossentry id="glossary-cluster-owner">
+   <glossterm>Cluster owner</glossterm>
+   <glossdef>
+    <para>
+     The operating system user that owns the
+     <glossterm linkend="glossary-data-directory">data directory</glossterm>
+     and under which the <literal>postgres</literal> process is run.
+     It is required that this user exist prior to creating a new
+     <glossterm linkend="glossary-db-cluster">database cluster</glossterm>.
+    </para>
+    <para>
+     On operating systems with a <literal>root</literal> user,
+     said user is not allowed to be the cluster owner.
+    </para>
+   </glossdef>
+  </glossentry>
+
   <glossentry id="glossary-column">
    <glossterm>Column</glossterm>
    <glossdef>
@@ -475,12 +511,20 @@
      and their common static and dynamic metadata.
      Sometimes referred to as a
      <firstterm>cluster</firstterm>.
+     A database cluster is created using the
+     <xref linkend="app-initdb" /> program.
     </para>
     <para>
      In <productname>PostgreSQL</productname>, the term
      <firstterm>cluster</firstterm> is also sometimes used to refer to an instance.
      (Don't confuse this term with the SQL command <command>CLUSTER</command>.)
     </para>
+    <para>
+     See also <glossterm linkend="glossary-cluster-owner">cluster owner</glossterm>,
+     the operating-system owner of a cluster,
+     and <glossterm linkend="glossary-bootstrap-superuser">bootstrap superuser</glossterm>,
+     the <productname>PostgreSQL</productname> owner of a cluster.
+    </para>
    </glossdef>
   </glossentry>
 
@@ -489,6 +533,19 @@
    <glosssee otherterm="glossary-instance" />
   </glossentry>
 
+  <glossentry id="glossary-database-superuser">
+   <glossterm>Database superuser</glossterm>
+   <glossdef>
+    <para>
+     A role having <firstterm>superuser status</firstterm>
+     (see <xref linkend="role-attributes"/>).
+    </para>
+    <para>
+     Frequently referred to as <firstterm>superuser</firstterm>.
+    </para>
+   </glossdef>
+  </glossentry>
+
   <glossentry id="glossary-data-directory">
    <glossterm>Data directory</glossterm>
    <glossdef>
@@ -1577,6 +1634,16 @@
    </glossdef>
   </glossentry>
 
+  <glossentry id="glossary-superuser">
+   <glossterm>Superuser</glossterm>
+   <glossdef>
+    <para>
+     As used in this documentation, it is a synonym for
+     <glossterm linkend="glossary-database-superuser">database superuser</glossterm>.
+    </para>
+   </glossdef>
+  </glossentry>
+
   <glossentry id="glossary-system-catalog">
    <glossterm>System catalog</glossterm>
    <glossdef>
@@ -1827,7 +1894,8 @@
    <glossdef>
     <para>
      A <glossterm linkend="glossary-role">role</glossterm> that has the
-     <literal>LOGIN</literal> privilege.
+     <firstterm>login privilege</firstterm>
+     (see <xref linkend="role-attributes"/>).
     </para>
    </glossdef>
   </glossentry>

diff --git a/doc/src/sgml/ref/initdb.sgml b/doc/src/sgml/ref/initdb.sgml
index 81588962980fa6c1958f103454618df2c2266ce8..2410330cd6c7858e9e5669894c321314d9e28eac 100644 (file)
--- a/doc/src/sgml/ref/initdb.sgml
+++ b/doc/src/sgml/ref/initdb.sgml
@@ -37,14 +37,13 @@ PostgreSQL documentation
   <title>Description</title>
   <para>
    <command>initdb</command> creates a new
-   <productname>PostgreSQL</productname> database cluster.  A database
-   cluster is a collection of databases that are managed by a single
-   server instance.
+   <productname>PostgreSQL</productname> <glossterm linkend="glossary-db-cluster">database cluster</glossterm>.
   </para>
 
   <para>
-   Creating a database cluster consists of creating the directories in
-   which the database data will live, generating the shared catalog
+   Creating a database cluster consists of creating the
+   <glossterm linkend="glossary-data-directory">directories</glossterm> in
+   which the cluster data will live, generating the shared catalog
    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.
@@ -196,7 +195,7 @@ PostgreSQL documentation
         <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.
        </para>
       </listitem>
@@ -338,7 +337,7 @@ PostgreSQL documentation
       <term><option>--pwfile=<replaceable>filename</replaceable></option></term>
       <listitem>
        <para>
-        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.
        </para>
       </listitem>
@@ -374,12 +373,10 @@ PostgreSQL documentation
       <term><option>--username=<replaceable class="parameter">username</replaceable></option></term>
       <listitem>
        <para>
-        Selects the user name of the database superuser. This defaults
-        to the name of the effective user running
-        <command>initdb</command>. It is really not important what the
-        superuser's name is, but one might choose to keep the
-        customary name <systemitem>postgres</systemitem>, even if the operating
-        system user's name is different.
+        Selects the user name of the
+        <glossterm linkend="glossary-bootstrap-superuser">boostrap superuser</glossterm>.
+        This defaults to the name of the
+        <glossterm linkend="glossary-cluster-owner">cluster owner</glossterm>.
        </para>
       </listitem>
      </varlistentry>
@@ -390,7 +387,7 @@ PostgreSQL documentation
       <listitem>
        <para>
         Makes <command>initdb</command> prompt for a password
-        to give the database superuser. If you don't plan on using password
+        to give the bootstrap superuser. If you don't plan on using password
         authentication, this is not important.  Otherwise you won't be
         able to use password authentication until you have a password
         set up.