begriffs open source - ai-pg/blob - full-docs/txt/server-start.txt

   1
   2 18.3. Starting the Database Server #
   3
   4    18.3.1. Server Start-up Failures
   5    18.3.2. Client Connection Problems
   6
   7    Before anyone can access the database, you must start the database
   8    server. The database server program is called postgres.
   9
  10    If you are using a pre-packaged version of PostgreSQL, it almost
  11    certainly includes provisions for running the server as a background
  12    task according to the conventions of your operating system. Using the
  13    package's infrastructure to start the server will be much less work
  14    than figuring out how to do this yourself. Consult the package-level
  15    documentation for details.
  16
  17    The bare-bones way to start the server manually is just to invoke
  18    postgres directly, specifying the location of the data directory with
  19    the -D option, for example:
  20 $ postgres -D /usr/local/pgsql/data
  21
  22    which will leave the server running in the foreground. This must be
  23    done while logged into the PostgreSQL user account. Without -D, the
  24    server will try to use the data directory named by the environment
  25    variable PGDATA. If that variable is not provided either, it will fail.
  26
  27    Normally it is better to start postgres in the background. For this,
  28    use the usual Unix shell syntax:
  29 $ postgres -D /usr/local/pgsql/data >logfile 2>&1 &
  30
  31    It is important to store the server's stdout and stderr output
  32    somewhere, as shown above. It will help for auditing purposes and to
  33    diagnose problems. (See Section 24.3 for a more thorough discussion of
  34    log file handling.)
  35
  36    The postgres program also takes a number of other command-line options.
  37    For more information, see the postgres reference page and Chapter 19
  38    below.
  39
  40    This shell syntax can get tedious quickly. Therefore the wrapper
  41    program pg_ctl is provided to simplify some tasks. For example:
  42 pg_ctl start -l logfile
  43
  44    will start the server in the background and put the output into the
  45    named log file. The -D option has the same meaning here as for
  46    postgres. pg_ctl is also capable of stopping the server.
  47
  48    Normally, you will want to start the database server when the computer
  49    boots. Autostart scripts are operating-system-specific. There are a few
  50    example scripts distributed with PostgreSQL in the
  51    contrib/start-scripts directory. Installing one will require root
  52    privileges.
  53
  54    Different systems have different conventions for starting up daemons at
  55    boot time. Many systems have a file /etc/rc.local or
  56    /etc/rc.d/rc.local. Others use init.d or rc.d directories. Whatever you
  57    do, the server must be run by the PostgreSQL user account and not by
  58    root or any other user. Therefore you probably should form your
  59    commands using su postgres -c '...'. For example:
  60 su postgres -c 'pg_ctl start -D /usr/local/pgsql/data -l serverlog'
  61
  62    Here are a few more operating-system-specific suggestions. (In each
  63    case be sure to use the proper installation directory and user name
  64    where we show generic values.)
  65      * For FreeBSD, look at the file contrib/start-scripts/freebsd in the
  66        PostgreSQL source distribution.
  67      * On OpenBSD, add the following lines to the file /etc/rc.local:
  68 if [ -x /usr/local/pgsql/bin/pg_ctl -a -x /usr/local/pgsql/bin/postgres ]; then
  69     su -l postgres -c '/usr/local/pgsql/bin/pg_ctl start -s -l /var/postgresql/l
  70 og -D /usr/local/pgsql/data'
  71     echo -n ' postgresql'
  72 fi
  73
  74      * On Linux systems either add
  75 /usr/local/pgsql/bin/pg_ctl start -l logfile -D /usr/local/pgsql/data
  76
  77        to /etc/rc.d/rc.local or /etc/rc.local or look at the file
  78        contrib/start-scripts/linux in the PostgreSQL source distribution.
  79        When using systemd, you can use the following service unit file
  80        (e.g., at /etc/systemd/system/postgresql.service):
  81 [Unit]
  82 Description=PostgreSQL database server
  83 Documentation=man:postgres(1)
  84 After=network-online.target
  85 Wants=network-online.target
  86
  87 [Service]
  88 Type=notify
  89 User=postgres
  90 ExecStart=/usr/local/pgsql/bin/postgres -D /usr/local/pgsql/data
  91 ExecReload=/bin/kill -HUP $MAINPID
  92 KillMode=mixed
  93 KillSignal=SIGINT
  94 TimeoutSec=infinity
  95
  96 [Install]
  97 WantedBy=multi-user.target
  98
  99        Using Type=notify requires that the server binary was built with
 100        configure --with-systemd.
 101        Consider carefully the timeout setting. systemd has a default
 102        timeout of 90 seconds as of this writing and will kill a process
 103        that does not report readiness within that time. But a PostgreSQL
 104        server that might have to perform crash recovery at startup could
 105        take much longer to become ready. The suggested value of infinity
 106        disables the timeout logic.
 107      * On NetBSD, use either the FreeBSD or Linux start scripts, depending
 108        on preference.
 109      * On Solaris, create a file called /etc/init.d/postgresql that
 110        contains the following line:
 111 su - postgres -c "/usr/local/pgsql/bin/pg_ctl start -l logfile -D /usr/local/pgs
 112 ql/data"
 113
 114        Then, create a symbolic link to it in /etc/rc3.d as S99postgresql.
 115
 116    While the server is running, its PID is stored in the file
 117    postmaster.pid in the data directory. This is used to prevent multiple
 118    server instances from running in the same data directory and can also
 119    be used for shutting down the server.
 120
 121 18.3.1. Server Start-up Failures #
 122
 123    There are several common reasons the server might fail to start. Check
 124    the server's log file, or start it by hand (without redirecting
 125    standard output or standard error) and see what error messages appear.
 126    Below we explain some of the most common error messages in more detail.
 127
 128 LOG:  could not bind IPv4 address "127.0.0.1": Address already in use
 129 HINT:  Is another postmaster already running on port 5432? If not, wait a few se
 130 conds and retry.
 131 FATAL:  could not create any TCP/IP sockets
 132
 133    This usually means just what it suggests: you tried to start another
 134    server on the same port where one is already running. However, if the
 135    kernel error message is not Address already in use or some variant of
 136    that, there might be a different problem. For example, trying to start
 137    a server on a reserved port number might draw something like:
 138 $ postgres -p 666
 139 LOG:  could not bind IPv4 address "127.0.0.1": Permission denied
 140 HINT:  Is another postmaster already running on port 666? If not, wait a few sec
 141 onds and retry.
 142 FATAL:  could not create any TCP/IP sockets
 143
 144    A message like:
 145 FATAL:  could not create shared memory segment: Invalid argument
 146 DETAIL:  Failed system call was shmget(key=5440001, size=4011376640, 03600).
 147
 148    probably means your kernel's limit on the size of shared memory is
 149    smaller than the work area PostgreSQL is trying to create (4011376640
 150    bytes in this example). This is only likely to happen if you have set
 151    shared_memory_type to sysv. In that case, you can try starting the
 152    server with a smaller-than-normal number of buffers (shared_buffers),
 153    or reconfigure your kernel to increase the allowed shared memory size.
 154    You might also see this message when trying to start multiple servers
 155    on the same machine, if their total space requested exceeds the kernel
 156    limit.
 157
 158    An error like:
 159 FATAL:  could not create semaphores: No space left on device
 160 DETAIL:  Failed system call was semget(5440126, 17, 03600).
 161
 162    does not mean you've run out of disk space. It means your kernel's
 163    limit on the number of System V semaphores is smaller than the number
 164    PostgreSQL wants to create. As above, you might be able to work around
 165    the problem by starting the server with a reduced number of allowed
 166    connections (max_connections), but you'll eventually want to increase
 167    the kernel limit.
 168
 169    Details about configuring System V IPC facilities are given in
 170    Section 18.4.1.
 171
 172 18.3.2. Client Connection Problems #
 173
 174    Although the error conditions possible on the client side are quite
 175    varied and application-dependent, a few of them might be directly
 176    related to how the server was started. Conditions other than those
 177    shown below should be documented with the respective client
 178    application.
 179
 180 psql: error: connection to server at "server.joe.com" (123.123.123.123), port 54
 181 32 failed: Connection refused
 182         Is the server running on that host and accepting TCP/IP connections?
 183
 184    This is the generic “I couldn't find a server to talk to” failure. It
 185    looks like the above when TCP/IP communication is attempted. A common
 186    mistake is to forget to configure listen_addresses so that the server
 187    accepts remote TCP connections.
 188
 189    Alternatively, you might get this when attempting Unix-domain socket
 190    communication to a local server:
 191 psql: error: connection to server on socket "/tmp/.s.PGSQL.5432" failed: No such
 192  file or directory
 193         Is the server running locally and accepting connections on that socket?
 194
 195    If the server is indeed running, check that the client's idea of the
 196    socket path (here /tmp) agrees with the server's
 197    unix_socket_directories setting.
 198
 199    A connection failure message always shows the server address or socket
 200    path name, which is useful in verifying that the client is trying to
 201    connect to the right place. If there is in fact no server listening
 202    there, the kernel error message will typically be either Connection
 203    refused or No such file or directory, as illustrated. (It is important
 204    to realize that Connection refused in this context does not mean that
 205    the server got your connection request and rejected it. That case will
 206    produce a different message, as shown in Section 20.16.) Other error
 207    messages such as Connection timed out might indicate more fundamental
 208    problems, like lack of network connectivity, or a firewall blocking the
 209    connection.