Received: from malur.postgresql.org ([217.196.149.56])
	by arkaria.postgresql.org with esmtps
 (TLS1.3:ECDHE_RSA_AES_256_GCM_SHA384:256)
	(Exim 4.92)
	(envelope-from <pgsql-docs-owner+archive@lists.postgresql.org>)
	id 1kDVrE-0004jS-3M
	for pgsql-docs@arkaria.postgresql.org; Wed, 02 Sep 2020 16:43:36 +0000
Received: from localhost ([127.0.0.1] helo=malur.postgresql.org)
	by malur.postgresql.org with esmtp (Exim 4.92)
	(envelope-from <pgsql-docs-owner+archive@lists.postgresql.org>)
	id 1kDVrB-0002mU-GG
	for pgsql-docs@arkaria.postgresql.org; Wed, 02 Sep 2020 16:43:33 +0000
Received: from makus.postgresql.org ([2001:4800:3e1:1::229])
	by malur.postgresql.org with esmtps (TLS1.3:ECDHE_RSA_AES_256_GCM_SHA384:256)
	(Exim 4.92)
	(envelope-from <tgl@sss.pgh.pa.us>)
	id 1kDVrB-0002mM-6D
	for pgsql-docs@lists.postgresql.org; Wed, 02 Sep 2020 16:43:33 +0000
Received: from sss.pgh.pa.us ([66.207.139.130])
	by makus.postgresql.org with esmtps (TLS1.3:ECDHE_RSA_AES_256_GCM_SHA384:256)
	(Exim 4.92)
	(envelope-from <tgl@sss.pgh.pa.us>)
	id 1kDVr4-0005a0-D6
	for pgsql-docs@lists.postgresql.org; Wed, 02 Sep 2020 16:43:31 +0000
Received: from sss1.sss.pgh.pa.us (localhost [127.0.0.1])
	by sss.pgh.pa.us (8.15.2/8.15.2) with ESMTP id 082GhICv338108;
	Wed, 2 Sep 2020 12:43:18 -0400
From: Tom Lane <tgl@sss.pgh.pa.us>
To: Daniel Gustafsson <daniel@yesql.se>
cc: Thomas Munro <thomas.munro@gmail.com>, Bruce Momjian <bruce@momjian.us>,
        gazzatav@gmail.com, Pg Docs <pgsql-docs@lists.postgresql.org>
Subject: Re: initdb - creating clusters
In-reply-to: <3166114A-AB6E-4216-B65B-2E51D41712AA@yesql.se>
References: <159430831443.16535.11360317280100947016@wrigleys.postgresql.org>
 <20200721002503.GA4065@momjian.us>
 <508F1D03-F896-4436-92B0-B9EA633BD1AE@yesql.se>
 <20200722163437.GA14522@momjian.us>
 <FB84D258-CED8-46BB-B30E-2006953F61AA@yesql.se>
 <CA+hUKGLjvXWn_O1PxAKXFEneGHrOos-QOe3try+ZbqPWrNiNrg@mail.gmail.com>
 <3793995.1598800896@sss.pgh.pa.us>
 <3166114A-AB6E-4216-B65B-2E51D41712AA@yesql.se>
Comments: In-reply-to Daniel Gustafsson <daniel@yesql.se>
	message dated "Wed, 02 Sep 2020 15:02:00 +0200"
MIME-Version: 1.0
Content-Type: multipart/mixed; boundary="----- =_aaaaaaaaaa0"
Content-ID: <338079.1599064973.0@sss.pgh.pa.us>
Date: Wed, 02 Sep 2020 12:43:18 -0400
Message-ID: <338107.1599064998@sss.pgh.pa.us>
List-Id: <pgsql-docs.lists.postgresql.org>
List-Help: <https://lists.postgresql.org/manage/>
List-Subscribe: <https://lists.postgresql.org/manage/>
List-Post: <mailto:pgsql-docs@lists.postgresql.org>
List-Owner: <mailto:pgsql-docs-owner@lists.postgresql.org>
List-Archive: <https://www.postgresql.org/list/pgsql-docs>
Precedence: bulk

------- =_aaaaaaaaaa0
Content-Type: text/plain; charset="us-ascii"
Content-ID: <338079.1599064973.1@sss.pgh.pa.us>
Content-Transfer-Encoding: quoted-printable

Daniel Gustafsson <daniel@yesql.se> writes:
> On 30 Aug 2020, at 17:21, Tom Lane <tgl@sss.pgh.pa.us> wrote:
>> Do you have a feeling one way or the other about whether to repeat
>> some of this text in each of the relevant sub-sections?  I initially
>> didn't want to do that, but thinking about how people consume the
>> HTML docs, I'm afraid that anything not appearing on the same page
>> won't get seen.

> I think you're right here, duplicating the content is probably required =
for it
> to be useful.

I took a stab at doing it that way, as attached.  (I couldn't resist
the temptation to do some minor editing on adjacent material, too.)

			regards, tom lane


------- =_aaaaaaaaaa0
Content-Type: text/x-diff;
	name="mention-package-installation-scripts-2.patch";
	charset="us-ascii"
Content-ID: <338079.1599064973.2@sss.pgh.pa.us>
Content-Description: mention-package-installation-scripts-2.patch
Content-Transfer-Encoding: quoted-printable

diff --git a/doc/src/sgml/runtime.sgml b/doc/src/sgml/runtime.sgml
index 6cda39f3ab..f584231935 100644
--- a/doc/src/sgml/runtime.sgml
+++ b/doc/src/sgml/runtime.sgml
@@ -4,10 +4,22 @@
  <title>Server Setup and Operation</title>
 =

  <para>
-  This chapter discusses how to set up and run the database server
+  This chapter discusses how to set up and run the database server,
   and its interactions with the operating system.
  </para>
 =

+ <para>
+  The directions in this chapter assume that you are working with
+  plain <productname>PostgreSQL</productname> without any additional
+  infrastructure, for example a copy that you built from source
+  according to the directions in the preceding chapters.
+  If you are working with a pre-packaged or vendor-supplied
+  version of <productname>PostgreSQL</productname>, it is likely that
+  the packager has made special provisions for installing and starting
+  the database server according to your system's conventions.
+  Consult the package-level documentation for details.
+ </para>
+
  <sect1 id=3D"postgres-user">
   <title>The <productname>PostgreSQL</productname> User Account</title>
 =

@@ -21,9 +33,15 @@
    separate user account. This user account should only own the data
    that is managed by the server, and should not be shared with other
    daemons. (For example, using the user <literal>nobody</literal> is a b=
ad
-   idea.) It is not advisable to install executables owned by this
-   user because compromised systems could then modify their own
-   binaries.
+   idea.) In particular, it is advisable that this user account not own
+   the <productname>PostgreSQL</productname> executable files, to ensure
+   that a compromised server process could not modify those executables.
+  </para>
+
+  <para>
+   Pre-packaged versions of <productname>PostgreSQL</productname> will
+   typically create a suitable user account automatically during
+   package installation.
   </para>
 =

   <para>
@@ -71,11 +89,26 @@
    completely up to you where you choose to store your data.  There is no
    default, although locations such as
    <filename>/usr/local/pgsql/data</filename> or
-   <filename>/var/lib/pgsql/data</filename> are popular. To initialize a
-   database cluster, use the command <xref
-   linkend=3D"app-initdb"/>,<indexterm><primary>initdb</primary></indexte=
rm> which is
-   installed with <productname>PostgreSQL</productname>. The desired
-   file system location of your database cluster is indicated by the
+   <filename>/var/lib/pgsql/data</filename> are popular.
+   The data directory must be initialized before being used, using the pr=
ogram
+   <xref linkend=3D"app-initdb"/><indexterm><primary>initdb</primary></in=
dexterm>
+   which is installed with <productname>PostgreSQL</productname>.
+  </para>
+
+  <para>
+   If you are using a pre-packaged version
+   of <productname>PostgreSQL</productname>, it may well have a specific
+   convention for where to place the data directory, and it may also
+   provide a script for creating the data directory.  In that case you
+   should use that script in preference to
+   running <command>initdb</command> directly.
+   Consult the package-level documentation for details.
+  </para>
+
+  <para>
+   To initialize a database cluster manually,
+   run <command>initdb</command> and specify the desired
+   file system location of the database cluster with the
    <option>-D</option> option, for example:
 <screen>
 <prompt>$</prompt> <userinput>initdb -D /usr/local/pgsql/data</userinput>
@@ -309,10 +342,22 @@ postgres$ <userinput>initdb -D /usr/local/pgsql/data=
</userinput>
    Before anyone can access the database, you must start the database
    server. The database server program is called
    <command>postgres</command>.<indexterm><primary>postgres</primary></in=
dexterm>
-   The <command>postgres</command> program must know where to
-   find the data it is supposed to use. This is done with the
-   <option>-D</option> option. Thus, the simplest way to start the
-   server is:
+  </para>
+
+  <para>
+   If you are using a pre-packaged version
+   of <productname>PostgreSQL</productname>, it almost certainly includes
+   provisions for running the server as a background task according to th=
e
+   conventions of your operating system.  Using the package's
+   infrastructure to start the server will be much less work than figurin=
g
+   out how to do this yourself.  Consult the package-level documentation
+   for details.
+  </para>
+
+  <para>
+   The bare-bones way to start the server manually is just to invoke
+   <command>postgres</command> directly, specifying the location of the
+   data directory with the <option>-D</option> option, for example:
 <screen>
 $ <userinput>postgres -D /usr/local/pgsql/data</userinput>
 </screen>
@@ -364,7 +409,7 @@ pg_ctl start -l logfile
      <secondary>starting the server during</secondary>
    </indexterm>
    Autostart scripts are operating-system-specific.
-   There are a few distributed with
+   There are a few example scripts distributed with
    <productname>PostgreSQL</productname> in the
    <filename>contrib/start-scripts</filename> directory. Installing one w=
ill require
    root privileges.
@@ -1481,9 +1526,23 @@ $ <userinput>cat /sys/kernel/mm/hugepages/hugepages=
-2048kB/nr_hugepages</userinp
   </indexterm>
 =

   <para>
-   There are several ways to shut down the database server. You control
-   the type of shutdown by sending different signals to the supervisor
+   There are several ways to shut down the database server.
+   Under the hood, they all reduce to sending a signal to the supervisor
    <command>postgres</command> process.
+  </para>
+
+  <para>
+   If you are using a pre-packaged version
+   of <productname>PostgreSQL</productname>, and you used its provisions
+   for starting the server, then you should also use its provisions for
+   stopping the server.  Consult the package-level documentation for
+   details.
+  </para>
+
+  <para>
+   When managing the server directly, you can control the type of shutdow=
n
+   by sending different signals to the <command>postgres</command>
+   process:
 =

    <variablelist>
     <varlistentry>
@@ -1620,6 +1679,10 @@ $ <userinput>kill -INT `head -1 /usr/local/pgsql/da=
ta/postmaster.pid`</userinput
    is to dump and reload the database, though this can be slow.  A
    faster method is <xref linkend=3D"pgupgrade"/>.  Replication methods a=
re
    also available, as discussed below.
+   (If you are using a pre-packaged version
+   of <productname>PostgreSQL</productname>, it may provide scripts to
+   assist with major version upgrades.  Consult the package-level
+   documentation for details.)
   </para>
 =

   <para>

------- =_aaaaaaaaaa0--