begriffs open source - ai-pg/blob - full-docs/src/sgml/html/server-start.html

   1 <?xml version="1.0" encoding="UTF-8" standalone="no"?>
   2 <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>18.3. Starting the Database Server</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="creating-cluster.html" title="18.2. Creating a Database Cluster" /><link rel="next" href="kernel-resources.html" title="18.4. Managing Kernel Resources" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">18.3. Starting the Database Server</th></tr><tr><td width="10%" align="left"><a accesskey="p" href="creating-cluster.html" title="18.2. Creating a Database Cluster">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="runtime.html" title="Chapter 18. Server Setup and Operation">Up</a></td><th width="60%" align="center">Chapter 18. Server Setup and Operation</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 18.0 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="kernel-resources.html" title="18.4. Managing Kernel Resources">Next</a></td></tr></table><hr /></div><div class="sect1" id="SERVER-START"><div class="titlepage"><div><div><h2 class="title" style="clear: both">18.3. Starting the Database Server <a href="#SERVER-START" class="id_link">#</a></h2></div></div></div><div class="toc"><dl class="toc"><dt><span class="sect2"><a href="server-start.html#SERVER-START-FAILURES">18.3.1. Server Start-up Failures</a></span></dt><dt><span class="sect2"><a href="server-start.html#CLIENT-CONNECTION-PROBLEMS">18.3.2. Client Connection Problems</a></span></dt></dl></div><p>
   3    Before anyone can access the database, you must start the database
   4    server. The database server program is called
   5    <code class="command">postgres</code>.<a id="id-1.6.5.6.2.2" class="indexterm"></a>
   6   </p><p>
   7    If you are using a pre-packaged version
   8    of <span class="productname">PostgreSQL</span>, it almost certainly includes
   9    provisions for running the server as a background task according to the
  10    conventions of your operating system.  Using the package's
  11    infrastructure to start the server will be much less work than figuring
  12    out how to do this yourself.  Consult the package-level documentation
  13    for details.
  14   </p><p>
  15    The bare-bones way to start the server manually is just to invoke
  16    <code class="command">postgres</code> directly, specifying the location of the
  17    data directory with the <code class="option">-D</code> option, for example:
  18 </p><pre class="screen">
  19 $ <strong class="userinput"><code>postgres -D /usr/local/pgsql/data</code></strong>
  20 </pre><p>
  21    which will leave the server running in the foreground. This must be
  22    done while logged into the <span class="productname">PostgreSQL</span> user
  23    account. Without <code class="option">-D</code>, the server will try to use
  24    the data directory named by the environment variable <code class="envar">PGDATA</code>.
  25    If that variable is not provided either, it will fail.
  26   </p><p>
  27    Normally it is better to start <code class="command">postgres</code> in the
  28    background.  For this, use the usual Unix shell syntax:
  29 </p><pre class="screen">
  30 $ <strong class="userinput"><code>postgres -D /usr/local/pgsql/data &gt;logfile 2&gt;&amp;1 &amp;</code></strong>
  31 </pre><p>
  32    It is important to store the server's <span class="systemitem">stdout</span> and
  33    <span class="systemitem">stderr</span> output somewhere, as shown above. It will help
  34    for auditing purposes and to diagnose problems. (See <a class="xref" href="logfile-maintenance.html" title="24.3. Log File Maintenance">Section 24.3</a> for a more thorough discussion of log
  35    file handling.)
  36   </p><p>
  37    The <code class="command">postgres</code> program also takes a number of other
  38    command-line options. For more information, see the
  39    <a class="xref" href="app-postgres.html" title="postgres"><span class="refentrytitle"><span class="application">postgres</span></span></a> reference page
  40    and <a class="xref" href="runtime-config.html" title="Chapter 19. Server Configuration">Chapter 19</a> below.
  41   </p><p>
  42    This shell syntax can get tedious quickly.  Therefore the wrapper
  43    program
  44    <a class="xref" href="app-pg-ctl.html" title="pg_ctl"><span class="refentrytitle"><span class="application">pg_ctl</span></span></a><a id="id-1.6.5.6.7.2" class="indexterm"></a>
  45    is provided to simplify some tasks.  For example:
  46 </p><pre class="programlisting">
  47 pg_ctl start -l logfile
  48 </pre><p>
  49    will start the server in the background and put the output into the
  50    named log file. The <code class="option">-D</code> option has the same meaning
  51    here as for <code class="command">postgres</code>. <code class="command">pg_ctl</code>
  52    is also capable of stopping the server.
  53   </p><p>
  54    Normally, you will want to start the database server when the
  55    computer boots.<a id="id-1.6.5.6.8.1" class="indexterm"></a>
  56    Autostart scripts are operating-system-specific.
  57    There are a few example scripts distributed with
  58    <span class="productname">PostgreSQL</span> in the
  59    <code class="filename">contrib/start-scripts</code> directory. Installing one will require
  60    root privileges.
  61   </p><p>
  62    Different systems have different conventions for starting up daemons
  63    at boot time. Many systems have a file
  64    <code class="filename">/etc/rc.local</code> or
  65    <code class="filename">/etc/rc.d/rc.local</code>. Others use <code class="filename">init.d</code> or
  66    <code class="filename">rc.d</code> directories. Whatever you do, the server must be
  67    run by the <span class="productname">PostgreSQL</span> user account
  68    <span class="emphasis"><em>and not by root</em></span> or any other user. Therefore you
  69    probably should form your commands using
  70    <code class="literal">su postgres -c '...'</code>.  For example:
  71 </p><pre class="programlisting">
  72 su postgres -c 'pg_ctl start -D /usr/local/pgsql/data -l serverlog'
  73 </pre><p>
  74   </p><p>
  75    Here are a few more operating-system-specific suggestions. (In each
  76    case be sure to use the proper installation directory and user
  77    name where we show generic values.)
  78
  79    </p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>
  80       For <span class="productname">FreeBSD</span>, look at the file
  81       <code class="filename">contrib/start-scripts/freebsd</code> in the
  82       <span class="productname">PostgreSQL</span> source distribution.
  83       <a id="id-1.6.5.6.10.1.1.1.4" class="indexterm"></a>
  84      </p></li><li class="listitem"><p>
  85       On <span class="productname">OpenBSD</span>, add the following lines
  86       to the file <code class="filename">/etc/rc.local</code>:
  87       <a id="id-1.6.5.6.10.1.2.1.3" class="indexterm"></a>
  88 </p><pre class="programlisting">
  89 if [ -x /usr/local/pgsql/bin/pg_ctl -a -x /usr/local/pgsql/bin/postgres ]; then
  90     su -l postgres -c '/usr/local/pgsql/bin/pg_ctl start -s -l /var/postgresql/log -D /usr/local/pgsql/data'
  91     echo -n ' postgresql'
  92 fi
  93 </pre><p>
  94      </p></li><li class="listitem"><p>
  95       On <span class="productname">Linux</span> systems either add
  96       <a id="id-1.6.5.6.10.1.3.1.2" class="indexterm"></a>
  97 </p><pre class="programlisting">
  98 /usr/local/pgsql/bin/pg_ctl start -l logfile -D /usr/local/pgsql/data
  99 </pre><p>
 100       to <code class="filename">/etc/rc.d/rc.local</code>
 101       or <code class="filename">/etc/rc.local</code> or look at the file
 102       <code class="filename">contrib/start-scripts/linux</code> in the
 103       <span class="productname">PostgreSQL</span> source distribution.
 104      </p><p>
 105       When using <span class="application">systemd</span>, you can use the following
 106       service unit file (e.g.,
 107       at <code class="filename">/etc/systemd/system/postgresql.service</code>):<a id="id-1.6.5.6.10.1.3.2.3" class="indexterm"></a>
 108 </p><pre class="programlisting">
 109 [Unit]
 110 Description=PostgreSQL database server
 111 Documentation=man:postgres(1)
 112 After=network-online.target
 113 Wants=network-online.target
 114
 115 [Service]
 116 Type=notify
 117 User=postgres
 118 ExecStart=/usr/local/pgsql/bin/postgres -D /usr/local/pgsql/data
 119 ExecReload=/bin/kill -HUP $MAINPID
 120 KillMode=mixed
 121 KillSignal=SIGINT
 122 TimeoutSec=infinity
 123
 124 [Install]
 125 WantedBy=multi-user.target
 126 </pre><p>
 127       Using <code class="literal">Type=notify</code> requires that the server binary was
 128       built with <code class="literal">configure --with-systemd</code>.
 129      </p><p>
 130       Consider carefully the timeout
 131       setting.  <span class="application">systemd</span> has a default timeout of 90
 132       seconds as of this writing and will kill a process that does not report
 133       readiness within that time.  But a <span class="productname">PostgreSQL</span>
 134       server that might have to perform crash recovery at startup could take
 135       much longer to become ready.  The suggested value
 136       of <code class="literal">infinity</code> disables the timeout logic.
 137      </p></li><li class="listitem"><p>
 138       On <span class="productname">NetBSD</span>, use either the
 139       <span class="productname">FreeBSD</span> or
 140       <span class="productname">Linux</span> start scripts, depending on
 141       preference.
 142       <a id="id-1.6.5.6.10.1.4.1.4" class="indexterm"></a>
 143      </p></li><li class="listitem"><p>
 144       On <span class="productname">Solaris</span>, create a file called
 145       <code class="filename">/etc/init.d/postgresql</code> that contains
 146       the following line:
 147       <a id="id-1.6.5.6.10.1.5.1.3" class="indexterm"></a>
 148 </p><pre class="programlisting">
 149 su - postgres -c "/usr/local/pgsql/bin/pg_ctl start -l logfile -D /usr/local/pgsql/data"
 150 </pre><p>
 151       Then, create a symbolic link to it in <code class="filename">/etc/rc3.d</code> as
 152       <code class="filename">S99postgresql</code>.
 153      </p></li></ul></div><p>
 154
 155   </p><p>
 156     While the server is running, its
 157     <acronym class="acronym">PID</acronym> is stored in the file
 158     <code class="filename">postmaster.pid</code> in the data directory. This is
 159     used to prevent multiple server instances from
 160     running in the same data directory and can also be used for
 161     shutting down the server.
 162    </p><div class="sect2" id="SERVER-START-FAILURES"><div class="titlepage"><div><div><h3 class="title">18.3.1. Server Start-up Failures <a href="#SERVER-START-FAILURES" class="id_link">#</a></h3></div></div></div><p>
 163      There are several common reasons the server might fail to
 164      start. Check the server's log file, or start it by hand (without
 165      redirecting standard output or standard error) and see what error
 166      messages appear. Below we explain some of the most common error
 167      messages in more detail.
 168     </p><p>
 169 </p><pre class="screen">
 170 LOG:  could not bind IPv4 address "127.0.0.1": Address already in use
 171 HINT:  Is another postmaster already running on port 5432? If not, wait a few seconds and retry.
 172 FATAL:  could not create any TCP/IP sockets
 173 </pre><p>
 174      This usually means just what it suggests: you tried to start
 175      another server on the same port where one is already running.
 176      However, if the kernel error message is not <code class="computeroutput">Address
 177      already in use</code> or some variant of that, there might
 178      be a different problem. For example, trying to start a server
 179      on a reserved port number might draw something like:
 180 </p><pre class="screen">
 181 $ <strong class="userinput"><code>postgres -p 666</code></strong>
 182 LOG:  could not bind IPv4 address "127.0.0.1": Permission denied
 183 HINT:  Is another postmaster already running on port 666? If not, wait a few seconds and retry.
 184 FATAL:  could not create any TCP/IP sockets
 185 </pre><p>
 186     </p><p>
 187      A message like:
 188 </p><pre class="screen">
 189 FATAL:  could not create shared memory segment: Invalid argument
 190 DETAIL:  Failed system call was shmget(key=5440001, size=4011376640, 03600).
 191 </pre><p>
 192      probably means your kernel's limit on the size of shared memory is
 193      smaller than the work area <span class="productname">PostgreSQL</span>
 194      is trying to create (4011376640 bytes in this example).
 195      This is only likely to happen if you have set <code class="literal">shared_memory_type</code>
 196      to <code class="literal">sysv</code>.  In that case, you
 197      can try starting the server with a smaller-than-normal number of
 198      buffers (<a class="xref" href="runtime-config-resource.html#GUC-SHARED-BUFFERS">shared_buffers</a>), or
 199      reconfigure your kernel to increase the allowed shared memory
 200      size. You might also see this message when trying to start multiple
 201      servers on the same machine, if their total space requested
 202      exceeds the kernel limit.
 203     </p><p>
 204      An error like:
 205 </p><pre class="screen">
 206 FATAL:  could not create semaphores: No space left on device
 207 DETAIL:  Failed system call was semget(5440126, 17, 03600).
 208 </pre><p>
 209      does <span class="emphasis"><em>not</em></span> mean you've run out of disk
 210      space. It means your kernel's limit on the number of <span class="systemitem">System V</span> semaphores is smaller than the number
 211      <span class="productname">PostgreSQL</span> wants to create. As above,
 212      you might be able to work around the problem by starting the
 213      server with a reduced number of allowed connections
 214      (<a class="xref" href="runtime-config-connection.html#GUC-MAX-CONNECTIONS">max_connections</a>), but you'll eventually want to
 215      increase the kernel limit.
 216     </p><p>
 217      Details about configuring <span class="systemitem">System V</span>
 218      <acronym class="acronym">IPC</acronym> facilities are given in <a class="xref" href="kernel-resources.html#SYSVIPC" title="18.4.1. Shared Memory and Semaphores">Section 18.4.1</a>.
 219     </p></div><div class="sect2" id="CLIENT-CONNECTION-PROBLEMS"><div class="titlepage"><div><div><h3 class="title">18.3.2. Client Connection Problems <a href="#CLIENT-CONNECTION-PROBLEMS" class="id_link">#</a></h3></div></div></div><p>
 220      Although the error conditions possible on the client side are quite
 221      varied and application-dependent, a few of them might be directly
 222      related to how the server was started. Conditions other than
 223      those shown below should be documented with the respective client
 224      application.
 225     </p><p>
 226 </p><pre class="screen">
 227 psql: error: connection to server at "server.joe.com" (123.123.123.123), port 5432 failed: Connection refused
 228         Is the server running on that host and accepting TCP/IP connections?
 229 </pre><p>
 230      This is the generic <span class="quote">“<span class="quote">I couldn't find a server to talk
 231      to</span>”</span> failure. It looks like the above when TCP/IP
 232      communication is attempted. A common mistake is to forget to
 233      configure <a class="xref" href="runtime-config-connection.html#GUC-LISTEN-ADDRESSES">listen_addresses</a> so that the server
 234      accepts remote TCP connections.
 235     </p><p>
 236      Alternatively, you might get this when attempting Unix-domain socket
 237      communication to a local server:
 238 </p><pre class="screen">
 239 psql: error: connection to server on socket "/tmp/.s.PGSQL.5432" failed: No such file or directory
 240         Is the server running locally and accepting connections on that socket?
 241 </pre><p>
 242      If the server is indeed running, check that the client's idea of the
 243      socket path (here <code class="literal">/tmp</code>) agrees with the server's
 244      <a class="xref" href="runtime-config-connection.html#GUC-UNIX-SOCKET-DIRECTORIES">unix_socket_directories</a> setting.
 245     </p><p>
 246      A connection failure message always shows the server address or socket
 247      path name, which is useful in verifying that the client is trying to
 248      connect to the right place. If there is in fact no server
 249      listening there, the kernel error message will typically be either
 250      <code class="computeroutput">Connection refused</code> or
 251      <code class="computeroutput">No such file or directory</code>, as
 252      illustrated. (It is important to realize that
 253      <code class="computeroutput">Connection refused</code> in this context
 254      does <span class="emphasis"><em>not</em></span> mean that the server got your
 255      connection request and rejected it. That case will produce a
 256      different message, as shown in <a class="xref" href="client-authentication-problems.html" title="20.16. Authentication Problems">Section 20.16</a>.) Other error messages
 257      such as <code class="computeroutput">Connection timed out</code> might
 258      indicate more fundamental problems, like lack of network
 259      connectivity, or a firewall blocking the connection.
 260     </p></div></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="creating-cluster.html" title="18.2. Creating a Database Cluster">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="runtime.html" title="Chapter 18. Server Setup and Operation">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="kernel-resources.html" title="18.4. Managing Kernel Resources">Next</a></td></tr><tr><td width="40%" align="left" valign="top">18.2. Creating a Database Cluster </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 18.0 Documentation">Home</a></td><td width="40%" align="right" valign="top"> 18.4. Managing Kernel Resources</td></tr></table></div></body></html>