Skip to content

Commit 910cab8

Browse files
alvherrealvherre
committed
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
1 parent 07f7237 commit 910cab8

File tree

3 files changed

+81
-16
lines changed

3 files changed

+81
-16
lines changed

‎doc/src/sgml/adminpack.sgml

+1-1
Original file line numberDiff line numberDiff line change
@@ -12,7 +12,7 @@
1212
<application>pgAdmin</application> and other administration and management tools can
1313
use to provide additional functionality, such as remote management
1414
of server log files.
15-
Use of all these functions is only allowed to the superuser by default but may be
15+
Use of all these functions is only allowed to database superusers by default, but may be
1616
allowed to other users by using the <command>GRANT</command> command.
1717
</para>
1818

‎doc/src/sgml/glossary.sgml

+69-1
Original file line numberDiff line numberDiff line change
@@ -233,6 +233,25 @@
233233
</glossdef>
234234
</glossentry>
235235

236+
<glossentry id="glossary-bootstrap-superuser">
237+
<glossterm>Bootstrap superuser</glossterm>
238+
<glossdef>
239+
<para>
240+
The first <glossterm linkend="glossary-user">user</glossterm> initialized in a
241+
<glossterm linkend="glossary-db-cluster">database cluster</glossterm>.
242+
</para>
243+
<para>
244+
This user owns all system catalog tables in each database. It is also the role
245+
from which all granted permissions originate. Because of these things, this
246+
role may not be dropped.
247+
</para>
248+
<para>
249+
This role also behaves as a normal
250+
<glossterm linkend="glossary-database-superuser">database superuser</glossterm>.
251+
</para>
252+
</glossdef>
253+
</glossentry>
254+
236255
<glossentry id="glossary-cast">
237256
<glossterm>Cast</glossterm>
238257
<glossdef>
@@ -342,6 +361,23 @@
342361
</glossdef>
343362
</glossentry>
344363

364+
<glossentry id="glossary-cluster-owner">
365+
<glossterm>Cluster owner</glossterm>
366+
<glossdef>
367+
<para>
368+
The operating system user that owns the
369+
<glossterm linkend="glossary-data-directory">data directory</glossterm>
370+
and under which the <literal>postgres</literal> process is run.
371+
It is required that this user exist prior to creating a new
372+
<glossterm linkend="glossary-db-cluster">database cluster</glossterm>.
373+
</para>
374+
<para>
375+
On operating systems with a <literal>root</literal> user,
376+
said user is not allowed to be the cluster owner.
377+
</para>
378+
</glossdef>
379+
</glossentry>
380+
345381
<glossentry id="glossary-column">
346382
<glossterm>Column</glossterm>
347383
<glossdef>
@@ -475,12 +511,20 @@
475511
and their common static and dynamic metadata.
476512
Sometimes referred to as a
477513
<firstterm>cluster</firstterm>.
514+
A database cluster is created using the
515+
<xref linkend="app-initdb" /> program.
478516
</para>
479517
<para>
480518
In <productname>PostgreSQL</productname>, the term
481519
<firstterm>cluster</firstterm> is also sometimes used to refer to an instance.
482520
(Don't confuse this term with the SQL command <command>CLUSTER</command>.)
483521
</para>
522+
<para>
523+
See also <glossterm linkend="glossary-cluster-owner">cluster owner</glossterm>,
524+
the operating-system owner of a cluster,
525+
and <glossterm linkend="glossary-bootstrap-superuser">bootstrap superuser</glossterm>,
526+
the <productname>PostgreSQL</productname> owner of a cluster.
527+
</para>
484528
</glossdef>
485529
</glossentry>
486530

@@ -489,6 +533,19 @@
489533
<glosssee otherterm="glossary-instance" />
490534
</glossentry>
491535

536+
<glossentry id="glossary-database-superuser">
537+
<glossterm>Database superuser</glossterm>
538+
<glossdef>
539+
<para>
540+
A role having <firstterm>superuser status</firstterm>
541+
(see <xref linkend="role-attributes"/>).
542+
</para>
543+
<para>
544+
Frequently referred to as <firstterm>superuser</firstterm>.
545+
</para>
546+
</glossdef>
547+
</glossentry>
548+
492549
<glossentry id="glossary-data-directory">
493550
<glossterm>Data directory</glossterm>
494551
<glossdef>
@@ -1577,6 +1634,16 @@
15771634
</glossdef>
15781635
</glossentry>
15791636

1637+
<glossentry id="glossary-superuser">
1638+
<glossterm>Superuser</glossterm>
1639+
<glossdef>
1640+
<para>
1641+
As used in this documentation, it is a synonym for
1642+
<glossterm linkend="glossary-database-superuser">database superuser</glossterm>.
1643+
</para>
1644+
</glossdef>
1645+
</glossentry>
1646+
15801647
<glossentry id="glossary-system-catalog">
15811648
<glossterm>System catalog</glossterm>
15821649
<glossdef>
@@ -1827,7 +1894,8 @@
18271894
<glossdef>
18281895
<para>
18291896
A <glossterm linkend="glossary-role">role</glossterm> that has the
1830-
<literal>LOGIN</literal> privilege.
1897+
<firstterm>login privilege</firstterm>
1898+
(see <xref linkend="role-attributes"/>).
18311899
</para>
18321900
</glossdef>
18331901
</glossentry>

‎doc/src/sgml/ref/initdb.sgml

+11-14
Original file line numberDiff line numberDiff line change
@@ -37,14 +37,13 @@ PostgreSQL documentation
3737
<title>Description</title>
3838
<para>
3939
<command>initdb</command> creates a new
40-
<productname>PostgreSQL</productname> database cluster. A database
41-
cluster is a collection of databases that are managed by a single
42-
server instance.
40+
<productname>PostgreSQL</productname> <glossterm linkend="glossary-db-cluster">database cluster</glossterm>.
4341
</para>
4442

4543
<para>
46-
Creating a database cluster consists of creating the directories in
47-
which the database data will live, generating the shared catalog
44+
Creating a database cluster consists of creating the
45+
<glossterm linkend="glossary-data-directory">directories</glossterm> in
46+
which the cluster data will live, generating the shared catalog
4847
tables (tables that belong to the whole cluster rather than to any
4948
particular database), and creating the <literal>postgres</literal>,
5049
<literal>template1</literal>, and <literal>template0</literal> databases.
@@ -196,7 +195,7 @@ PostgreSQL documentation
196195
<command>initdb</command>, but you can avoid writing it by
197196
setting the <envar>PGDATA</envar> environment variable, which
198197
can be convenient since the database server
199-
(<command>postgres</command>) can find the database
198+
(<command>postgres</command>) can find the data
200199
directory later by the same variable.
201200
</para>
202201
</listitem>
@@ -338,7 +337,7 @@ PostgreSQL documentation
338337
<term><option>--pwfile=<replaceable>filename</replaceable></option></term>
339338
<listitem>
340339
<para>
341-
Makes <command>initdb</command> read the database superuser's password
340+
Makes <command>initdb</command> read the bootstrap superuser's password
342341
from a file. The first line of the file is taken as the password.
343342
</para>
344343
</listitem>
@@ -374,12 +373,10 @@ PostgreSQL documentation
374373
<term><option>--username=<replaceable class="parameter">username</replaceable></option></term>
375374
<listitem>
376375
<para>
377-
Selects the user name of the database superuser. This defaults
378-
to the name of the effective user running
379-
<command>initdb</command>. It is really not important what the
380-
superuser's name is, but one might choose to keep the
381-
customary name <systemitem>postgres</systemitem>, even if the operating
382-
system user's name is different.
376+
Selects the user name of the
377+
<glossterm linkend="glossary-bootstrap-superuser">boostrap superuser</glossterm>.
378+
This defaults to the name of the
379+
<glossterm linkend="glossary-cluster-owner">cluster owner</glossterm>.
383380
</para>
384381
</listitem>
385382
</varlistentry>
@@ -390,7 +387,7 @@ PostgreSQL documentation
390387
<listitem>
391388
<para>
392389
Makes <command>initdb</command> prompt for a password
393-
to give the database superuser. If you don't plan on using password
390+
to give the bootstrap superuser. If you don't plan on using password
394391
authentication, this is not important. Otherwise you won't be
395392
able to use password authentication until you have a password
396393
set up.

0 commit comments

Comments
 (0)