From 214bc9038e39e209924514b77db4ee491f95509a Mon Sep 17 00:00:00 2001 From: Tom Lane Date: Thu, 3 Sep 2020 11:45:26 -0400 Subject: [PATCH] Doc: mention packager-supplied tools for server start/stop, initdb, etc. The majority of our audience is probably using a pre-packaged Postgres build rather than raw sources. For them, much of runtime.sgml is not too relevant, and they should be reading the packager's docs instead. Add some notes pointing that way in appropriate places. Text by me; thanks to Daniel Gustafsson for review and discussion, and to Laurenz Albe for an earlier version. Discussion: https://postgr.es/m/159430831443.16535.11360317280100947016@wrigleys.postgresql.org --- doc/src/sgml/runtime.sgml | 95 ++++++++++++++++++++++++++++++++------- 1 file changed, 79 insertions(+), 16 deletions(-) diff --git a/doc/src/sgml/runtime.sgml b/doc/src/sgml/runtime.sgml index 4b41cdefda..4d1d6fa8b5 100644 --- a/doc/src/sgml/runtime.sgml +++ b/doc/src/sgml/runtime.sgml @@ -4,10 +4,22 @@ Server Setup and Operation - 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. + + The directions in this chapter assume that you are working with + plain PostgreSQL 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 PostgreSQL, 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. + + The <productname>PostgreSQL</productname> User Account @@ -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 nobody 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 PostgreSQL executable files, to ensure + that a compromised server process could not modify those executables. + + + + Pre-packaged versions of PostgreSQL will + typically create a suitable user account automatically during + package installation. @@ -71,11 +89,26 @@ completely up to you where you choose to store your data. There is no default, although locations such as /usr/local/pgsql/data or - /var/lib/pgsql/data are popular. To initialize a - database cluster, use the command ,initdb which is - installed with PostgreSQL. The desired - file system location of your database cluster is indicated by the + /var/lib/pgsql/data are popular. + The data directory must be initialized before being used, using the program + initdb + which is installed with PostgreSQL. + + + + If you are using a pre-packaged version + of PostgreSQL, 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 initdb directly. + Consult the package-level documentation for details. + + + + To initialize a database cluster manually, + run initdb and specify the desired + file system location of the database cluster with the option, for example: $ initdb -D /usr/local/pgsql/data @@ -309,10 +342,22 @@ postgres$ initdb -D /usr/local/pgsql/data Before anyone can access the database, you must start the database server. The database server program is called postgres.postgres - The postgres program must know where to - find the data it is supposed to use. This is done with the - option. Thus, the simplest way to start the - server is: + + + + If you are using a pre-packaged version + of PostgreSQL, 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. + + + + The bare-bones way to start the server manually is just to invoke + postgres directly, specifying the location of the + data directory with the option, for example: $ postgres -D /usr/local/pgsql/data @@ -364,7 +409,7 @@ pg_ctl start -l logfile starting the server during Autostart scripts are operating-system-specific. - There are a few distributed with + There are a few example scripts distributed with PostgreSQL in the contrib/start-scripts directory. Installing one will require root privileges. @@ -1466,9 +1511,23 @@ $ grep Huge /proc/meminfo - There are several ways to shut down the database server. You control - the type of shutdown by sending different signals to the master + There are several ways to shut down the database server. + Under the hood, they all reduce to sending a signal to the supervisor postgres process. + + + + If you are using a pre-packaged version + of PostgreSQL, 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. + + + + When managing the server directly, you can control the type of shutdown + by sending different signals to the postgres + process: @@ -1605,6 +1664,10 @@ $ kill -INT `head -1 /usr/local/pgsql/data/postmaster.pid`. Replication methods are also available, as discussed below. + (If you are using a pre-packaged version + of PostgreSQL, it may provide scripts to + assist with major version upgrades. Consult the package-level + documentation for details.)