codekingpro/portable-devtools
115k
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>19.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="19.2. Creating a Database Cluster" /><link rel="next" href="kernel-resources.html" title="19.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">19.3. Starting the Database Server</th></tr><tr><td width="10%" align="left"><a accesskey="p" href="creating-cluster.html" title="19.2. Creating a Database Cluster">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="runtime.html" title="Chapter 19. Server Setup and Operation">Up</a></td><th width="60%" align="center">Chapter 19. Server Setup and Operation</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 16.3 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="kernel-resources.html" title="19.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">19.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">19.3.1. Server Start-up Failures</a></span></dt><dt><span class="sect2"><a href="server-start.html#CLIENT-CONNECTION-PROBLEMS">19.3.2. Client Connection Problems</a></span></dt></dl></div><p>3 Before anyone can access the database, you must start the database4 server. The database server program is called5 <code class="command">postgres</code>.<a id="id-1.6.6.6.2.2" class="indexterm"></a>6 </p><p>7 If you are using a pre-packaged version8 of <span class="productname">PostgreSQL</span>, it almost certainly includes9 provisions for running the server as a background task according to the10 conventions of your operating system. Using the package's11 infrastructure to start the server will be much less work than figuring12 out how to do this yourself. Consult the package-level documentation13 for details.14 </p><p>15 The bare-bones way to start the server manually is just to invoke16 <code class="command">postgres</code> directly, specifying the location of the17 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 be22 done while logged into the <span class="productname">PostgreSQL</span> user23 account. Without <code class="option">-D</code>, the server will try to use24 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 the28 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 >logfile 2>&1 &</code></strong>31</pre><p>32 It is important to store the server's <span class="systemitem">stdout</span> and33 <span class="systemitem">stderr</span> output somewhere, as shown above. It will help34 for auditing purposes and to diagnose problems. (See <a class="xref" href="logfile-maintenance.html" title="25.3. Log File Maintenance">Section 25.3</a> for a more thorough discussion of log35 file handling.)36 </p><p>37 The <code class="command">postgres</code> program also takes a number of other38 command-line options. For more information, see the39 <a class="xref" href="app-postgres.html" title="postgres"><span class="refentrytitle"><span class="application">postgres</span></span></a> reference page40 and <a class="xref" href="runtime-config.html" title="Chapter 20. Server Configuration">Chapter 20</a> below.41 </p><p>42 This shell syntax can get tedious quickly. Therefore the wrapper43 program44 <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.6.6.7.2" class="indexterm"></a>45 is provided to simplify some tasks. For example:46</p><pre class="programlisting">47pg_ctl start -l logfile48</pre><p>49 will start the server in the background and put the output into the50 named log file. The <code class="option">-D</code> option has the same meaning51 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 the55 computer boots.<a id="id-1.6.6.6.8.1" class="indexterm"></a>56 Autostart scripts are operating-system-specific.57 There are a few example scripts distributed with58 <span class="productname">PostgreSQL</span> in the59 <code class="filename">contrib/start-scripts</code> directory. Installing one will require60 root privileges.61 </p><p>62 Different systems have different conventions for starting up daemons63 at boot time. Many systems have a file64 <code class="filename">/etc/rc.local</code> or65 <code class="filename">/etc/rc.d/rc.local</code>. Others use <code class="filename">init.d</code> or66 <code class="filename">rc.d</code> directories. Whatever you do, the server must be67 run by the <span class="productname">PostgreSQL</span> user account68 <span class="emphasis"><em>and not by root</em></span> or any other user. Therefore you69 probably should form your commands using70 <code class="literal">su postgres -c '...'</code>. For example:71</p><pre class="programlisting">72su 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 each76 case be sure to use the proper installation directory and user77 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 file81 <code class="filename">contrib/start-scripts/freebsd</code> in the82 <span class="productname">PostgreSQL</span> source distribution.83 <a id="id-1.6.6.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 lines86 to the file <code class="filename">/etc/rc.local</code>:87 <a id="id-1.6.6.6.10.1.2.1.3" class="indexterm"></a>88</p><pre class="programlisting">89if [ -x /usr/local/pgsql/bin/pg_ctl -a -x /usr/local/pgsql/bin/postgres ]; then90 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'92fi93</pre><p>94 </p></li><li class="listitem"><p>95 On <span class="productname">Linux</span> systems either add96 <a id="id-1.6.6.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/data99</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 file102 <code class="filename">contrib/start-scripts/linux</code> in the103 <span class="productname">PostgreSQL</span> source distribution.104 </p><p>105 When using <span class="application">systemd</span>, you can use the following106 service unit file (e.g.,107 at <code class="filename">/etc/systemd/system/postgresql.service</code>):<a id="id-1.6.6.6.10.1.3.2.3" class="indexterm"></a>108</p><pre class="programlisting">109[Unit]110Description=PostgreSQL database server111Documentation=man:postgres(1)112After=network-online.target113Wants=network-online.target114 115[Service]116Type=notify117User=postgres118ExecStart=/usr/local/pgsql/bin/postgres -D /usr/local/pgsql/data119ExecReload=/bin/kill -HUP $MAINPID120KillMode=mixed121KillSignal=SIGINT122TimeoutSec=infinity123 124[Install]125WantedBy=multi-user.target126</pre><p>127 Using <code class="literal">Type=notify</code> requires that the server binary was128 built with <code class="literal">configure --with-systemd</code>.129 </p><p>130 Consider carefully the timeout131 setting. <span class="application">systemd</span> has a default timeout of 90132 seconds as of this writing and will kill a process that does not report133 readiness within that time. But a <span class="productname">PostgreSQL</span>134 server that might have to perform crash recovery at startup could take135 much longer to become ready. The suggested value136 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 the139 <span class="productname">FreeBSD</span> or140 <span class="productname">Linux</span> start scripts, depending on141 preference.142 <a id="id-1.6.6.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 called145 <code class="filename">/etc/init.d/postgresql</code> that contains146 the following line:147 <a id="id-1.6.6.6.10.1.5.1.3" class="indexterm"></a>148</p><pre class="programlisting">149su - 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> as152 <code class="filename">S99postgresql</code>.153 </p></li></ul></div><p>154 155 </p><p>156 While the server is running, its157 <acronym class="acronym">PID</acronym> is stored in the file158 <code class="filename">postmaster.pid</code> in the data directory. This is159 used to prevent multiple server instances from160 running in the same data directory and can also be used for161 shutting down the server.162 </p><div class="sect2" id="SERVER-START-FAILURES"><div class="titlepage"><div><div><h3 class="title">19.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 to164 start. Check the server's log file, or start it by hand (without165 redirecting standard output or standard error) and see what error166 messages appear. Below we explain some of the most common error167 messages in more detail.168 </p><p>169</p><pre class="screen">170LOG: could not bind IPv4 address "127.0.0.1": Address already in use171HINT: Is another postmaster already running on port 5432? If not, wait a few seconds and retry.172FATAL: could not create any TCP/IP sockets173</pre><p>174 This usually means just what it suggests: you tried to start175 another server on the same port where one is already running.176 However, if the kernel error message is not <code class="computeroutput">Address177 already in use</code> or some variant of that, there might178 be a different problem. For example, trying to start a server179 on a reserved port number might draw something like:180</p><pre class="screen">181$ <strong class="userinput"><code>postgres -p 666</code></strong>182LOG: could not bind IPv4 address "127.0.0.1": Permission denied183HINT: Is another postmaster already running on port 666? If not, wait a few seconds and retry.184FATAL: could not create any TCP/IP sockets185</pre><p>186 </p><p>187 A message like:188</p><pre class="screen">189FATAL: could not create shared memory segment: Invalid argument190DETAIL: 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 is193 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, you197 can try starting the server with a smaller-than-normal number of198 buffers (<a class="xref" href="runtime-config-resource.html#GUC-SHARED-BUFFERS">shared_buffers</a>), or199 reconfigure your kernel to increase the allowed shared memory200 size. You might also see this message when trying to start multiple201 servers on the same machine, if their total space requested202 exceeds the kernel limit.203 </p><p>204 An error like:205</p><pre class="screen">206FATAL: could not create semaphores: No space left on device207DETAIL: 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 disk210 space. It means your kernel's limit on the number of <span class="systemitem">System V</span> semaphores is smaller than the number211 <span class="productname">PostgreSQL</span> wants to create. As above,212 you might be able to work around the problem by starting the213 server with a reduced number of allowed connections214 (<a class="xref" href="runtime-config-connection.html#GUC-MAX-CONNECTIONS">max_connections</a>), but you'll eventually want to215 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="19.4.1. Shared Memory and Semaphores">Section 19.4.1</a>.219 </p></div><div class="sect2" id="CLIENT-CONNECTION-PROBLEMS"><div class="titlepage"><div><div><h3 class="title">19.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 quite221 varied and application-dependent, a few of them might be directly222 related to how the server was started. Conditions other than223 those shown below should be documented with the respective client224 application.225 </p><p>226</p><pre class="screen">227psql: error: connection to server at "server.joe.com" (123.123.123.123), port 5432 failed: Connection refused228 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 talk231 to</span>”</span> failure. It looks like the above when TCP/IP232 communication is attempted. A common mistake is to forget to233 configure the server to allow TCP/IP connections.234 </p><p>235 Alternatively, you might get this when attempting Unix-domain socket236 communication to a local server:237</p><pre class="screen">238psql: error: connection to server on socket "/tmp/.s.PGSQL.5432" failed: No such file or directory239 Is the server running locally and accepting connections on that socket?240</pre><p>241 If the server is indeed running, check that the client's idea of the242 socket path (here <code class="literal">/tmp</code>) agrees with the server's243 <a class="xref" href="runtime-config-connection.html#GUC-UNIX-SOCKET-DIRECTORIES">unix_socket_directories</a> setting.244 </p><p>245 A connection failure message always shows the server address or socket246 path name, which is useful in verifying that the client is trying to247 connect to the right place. If there is in fact no server248 listening there, the kernel error message will typically be either249 <code class="computeroutput">Connection refused</code> or250 <code class="computeroutput">No such file or directory</code>, as251 illustrated. (It is important to realize that252 <code class="computeroutput">Connection refused</code> in this context253 does <span class="emphasis"><em>not</em></span> mean that the server got your254 connection request and rejected it. That case will produce a255 different message, as shown in <a class="xref" href="client-authentication-problems.html" title="21.15. Authentication Problems">Section 21.15</a>.) Other error messages256 such as <code class="computeroutput">Connection timed out</code> might257 indicate more fundamental problems, like lack of network258 connectivity, or a firewall blocking the connection.259 </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="19.2. Creating a Database Cluster">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="runtime.html" title="Chapter 19. Server Setup and Operation">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="kernel-resources.html" title="19.4. Managing Kernel Resources">Next</a></td></tr><tr><td width="40%" align="left" valign="top">19.2. Creating a Database Cluster </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 16.3 Documentation">Home</a></td><td width="40%" align="right" valign="top"> 19.4. Managing Kernel Resources</td></tr></table></div></body></html>