From: Tom Lane <tgl@sss.pgh.pa.us>
To: Daniel Gustafsson <daniel@yesql.se>
Cc: Thomas Munro <thomas.munro@gmail.com>
Cc: Bruce Momjian <bruce@momjian.us>
Cc: gazzatav@gmail.com, Pg Docs <pgsql-docs@lists.postgresql.org>
Subject: Re: initdb - creating clusters
Date: Wed, 02 Sep 2020 12:43:18 -0400
Message-ID: <338107.1599064998@sss.pgh.pa.us> (raw)
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>
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
Attachments:mention-package-installation-scripts-2.patch (text/x-diff, 6.5K) downloaddiff --git a/doc/src/sgml/runtime.sgml b/doc/src/sgml/runtime.sgmlindex 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="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 bad
- 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="app-initdb"/>,<indexterm><primary>initdb</primary></indexterm> 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 program+ <xref linkend="app-initdb"/><indexterm><primary>initdb</primary></indexterm>+ 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></indexterm>
- 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 the+ conventions of your operating system. Using the package's+ infrastructure to start the server will be much less work than figuring+ 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 will 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 shutdown+ by sending different signals to the <command>postgres</command>+ process:
<variablelist>
<varlistentry>
@@ -1620,6 +1679,10 @@ $ <userinput>kill -INT `head -1 /usr/local/pgsql/data/postmaster.pid`</userinput
is to dump and reload the database, though this can be slow. A
faster method is <xref linkend="pgupgrade"/>. Replication methods are
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>
Reply instructions:
You may reply publicly to this message via plain-text email
using any one of the following methods:
* Reply to all the recipients using the --to and --cc options:
reply via email
To: pgsql-docs@postgresql.org
Cc: tgl@sss.pgh.pa.us, daniel@yesql.se, thomas.munro@gmail.com, bruce@momjian.us, pgsql-docs@lists.postgresql.org
Subject: Re: initdb - creating clusters
In-Reply-To: <338107.1599064998@sss.pgh.pa.us>
* Save the following mbox file, import it into your mail client,
and reply-to-all from there: mbox
This inbox is served by DDX for PostgreSQL; see mirroring instructions
for how to clone and mirror all data and code used for this inbox