commit 2873a9c32f0843f227c43f234960e48b3b118a49 Author: David G. Johnston Date: Tue Nov 1 22:48:58 2022 +0000 initdb and glossary diff --git a/doc/src/sgml/adminpack.sgml b/doc/src/sgml/adminpack.sgml index 1150b7f5bb..184e96d7a0 100644 --- a/doc/src/sgml/adminpack.sgml +++ b/doc/src/sgml/adminpack.sgml @@ -12,7 +12,7 @@ pgAdmin 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 GRANT command. diff --git a/doc/src/sgml/glossary.sgml b/doc/src/sgml/glossary.sgml index d6d0a3a814..f0c4f3a389 100644 --- a/doc/src/sgml/glossary.sgml +++ b/doc/src/sgml/glossary.sgml @@ -233,6 +233,25 @@ + + Bootstrap superuser + + + The first user initialized in a + database cluster. + + + This user owns all system catalog tables in each database. It also is the role + from which all granted permissions originate. Because of these things, this + role may not be dropped. + + + This role also behaves as a normal + database superuser + + + + Cast @@ -342,6 +361,28 @@ + + Cluster owner + + + This is the term given to identify the operating system user that owns + the data directory and under which the postgres process is run. + It is required that this user exist prior to creating a new + database cluster. + + + On operating systems with a root user, + that the root user must not be the cluster owner. + + + A cluster owner, by virtue of having full access to the database files, also can assume + the identity of any database superuser. + The reverse is also true since PostgreSQL provides various ways + to execute commands in the operating system. + + + + Column @@ -475,12 +516,20 @@ and their common static and dynamic metadata. Sometimes referred to as a cluster. + A database cluster is created using the + program. In PostgreSQL, the term cluster is also sometimes used to refer to an instance. (Don't confuse this term with the SQL command CLUSTER.) + + See also cluster owner, + the operating-system owner of a cluster, + and bootstrap superuser, + the PostgreSQL owner of a cluster. + @@ -489,6 +538,29 @@ + + Database superuser + + + A role having the superuser attribute (see ). + + + All superusers in the system are collectively referred to as database superusers throughout + the documentation. Any plain use of the term + superuser + can be interpreted to mean database superuser. + + + While the bootstrap superuser is + a database superuser, it has special obligations and restrictions that plain database superusers do not. + + + A database superuser, through various facilities provided by the server, also assumes the identity of + the cluster owner. And vice-versa. + + + + Data directory @@ -1577,6 +1649,16 @@ + + Superuser + + + As used in this documentation, it is a synonym for + database superuser. + + + + System catalog diff --git a/doc/src/sgml/ref/initdb.sgml b/doc/src/sgml/ref/initdb.sgml index 8158896298..96442fd68c 100644 --- a/doc/src/sgml/ref/initdb.sgml +++ b/doc/src/sgml/ref/initdb.sgml @@ -37,17 +37,18 @@ PostgreSQL documentation Description initdb creates a new - PostgreSQL database cluster. A database - cluster is a collection of databases that are managed by a single - server instance. + PostgreSQL database cluster. - 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 directories 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 postgres, - template1, and template0 databases. + particular database), creating the postgres, + template1, and template0 databases, + and creating the + boostrap superuser. The postgres database is a default database meant for use by users, utilities and third party applications. template1 and template0 are @@ -59,30 +60,19 @@ PostgreSQL documentation - Although initdb will attempt to create the - specified data directory, it might not have permission if the parent - directory of the desired data directory is root-owned. To initialize - in such a setup, create an empty data directory as root, then use - chown to assign ownership of that directory to the - database user account, then su to become the - database user to run initdb. + initdb must be run by the intended + cluster owner. + The initialization process includes creating the data directory and + setting its permissions and ownership. You must ensure either that the + cluster owner is able to create that directory, or that such a directory + already exists and is empty. See the notes section for more details + regarding the security of the data directory. - initdb must be run as the user that will own the - server process, because the server needs to have access to the - files and directories that initdb creates. - Since the server cannot be run as root, you must not run - initdb as root either. (It will in fact refuse - to do so.) - - - - For security reasons the new cluster created by initdb - will only be accessible by the cluster owner by default. The - option allows any user in the same - group as the cluster owner to read files in the cluster. This is useful - for performing backups as a non-privileged user. + By default, the cluster owner's user name will be used for the newly created + boostrap superuser's + role name. You can override this via the option. @@ -196,7 +186,7 @@ PostgreSQL documentation initdb, but you can avoid writing it by setting the PGDATA environment variable, which can be convenient since the database server - (postgres) can find the database + (postgres) can find the data directory later by the same variable. @@ -223,10 +213,14 @@ PostgreSQL documentation - Allows users in the same group as the cluster owner to read all cluster - files created by initdb. This option is ignored - on Windows as it does not support - POSIX-style group permissions. + Ignored by systems that do not use POSIX-style + group permissions (most notably Windows). Forces the group permission + flag to read+execute from the default of no permissions. See notes for + more details. + + + This is mainly useful for enabling an unprivileged account to perform system + administration tasks, like backups, on the directory. @@ -338,7 +332,7 @@ PostgreSQL documentation - Makes initdb read the database superuser's password + Makes initdb read the bootstrap superuser's password from a file. The first line of the file is taken as the password. @@ -349,7 +343,7 @@ PostgreSQL documentation - 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 perform any of the normal initdb operations. Generally, this option is useful for ensuring reliable recovery after changing from off to @@ -374,12 +368,11 @@ PostgreSQL documentation - Selects the user name of the database superuser. This defaults - to the name of the effective user running - initdb. It is really not important what the - superuser's name is, but one might choose to keep the - customary name postgres, even if the operating - system user's name is different. + Selects the user name of the + boostrap superuser. + This defaults to the name of the + cluster owner. + See the notes section for more details as to how these names are used. @@ -390,7 +383,7 @@ PostgreSQL documentation Makes initdb 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. @@ -422,7 +415,7 @@ PostgreSQL documentation 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 performance and management problem. Increasing the WAL file size will reduce the number of WAL files. @@ -569,10 +562,43 @@ PostgreSQL documentation Notes + + On systems using POSIX-style permissions the data directory, + and all of its contents, will be forced to have permissions of 700, though you can + use to instead force 750. In either case, + the effective user running initdb (i.e., the + cluster owner) + will become the owner and group for data directory and its contents. + + + + On systems with a special root user + PostgreSQL will fail if the + cluster owner + is root. This probably conflicts with the fact that the + data directory is likely to be placed in a location owned by root. + In this situation the suggested process is to create an empty data directory, + as root, then use chown to assign ownership of that directory, + to the cluster owner, then su to become the + cluster owner to run initdb. + + + + It is not important what the bootstrap superuser's name is, but one might choose to keep the + customary name postgres, even if the cluster owner's name is different. + In particular, because the default database name is postgres, and the libpq + default connection convention is that the name of the database being connected to matches the user name + making the connection. However, peer authentication relies on the operating system user and + database user names being identical (unless you use an identity map) so leaving the bootstrap superuser + name equal to the cluster owner name makes connecting as the bootstrap superuser a bit less cumbersome. + Having all three be the conventional postgres meets both conventions. + + initdb can also be invoked via pg_ctl initdb. +