pg_ctl-ref.sgml 14.1 KB
Newer Older
1
<!--
2
$PostgreSQL: pgsql/doc/src/sgml/ref/pg_ctl-ref.sgml,v 1.30 2004/12/22 02:17:15 momjian Exp $
3
PostgreSQL documentation
4 5
-->

Peter Eisentraut's avatar
Peter Eisentraut committed
6
<refentry id="app-pg-ctl">
7
 <refmeta>
8 9
  <refentrytitle id="app-pg-ctl-title"><application>pg_ctl</application></refentrytitle>
  <manvolnum>1</manvolnum>
10 11 12 13
  <refmiscinfo>Application</refmiscinfo>
 </refmeta>

 <refnamediv>
14
  <refname>pg_ctl</refname>
15
  <refpurpose>start, stop, or restart a <productname>PostgreSQL</productname> server</refpurpose>
16 17
 </refnamediv>

Peter Eisentraut's avatar
Peter Eisentraut committed
18 19 20 21
 <indexterm zone="app-pg-ctl">
  <primary>pg_ctl</primary>
 </indexterm>

22
 <refsynopsisdiv>
23 24 25 26
  <cmdsynopsis>
   <command>pg_ctl</command>
   <arg choice="plain">start</arg>
   <arg>-w</arg>
27
   <arg>-s</arg>
28
   <arg>-D <replaceable>datadir</replaceable></arg>
29
   <arg>-l <replaceable>filename</replaceable></arg>
30
   <arg>-o <replaceable>options</replaceable></arg>
31
   <arg>-p <replaceable>path</replaceable></arg>
32 33 34
   <sbr>
   <command>pg_ctl</command>
   <arg choice="plain">stop</arg>
35
   <arg>-W</arg>
36
   <arg>-s</arg>
37 38 39 40 41 42 43 44 45 46 47 48
   <arg>-D <replaceable>datadir</replaceable></arg>
   <arg>-m
     <group choice="plain">
       <arg>s[mart]</arg>
       <arg>f[ast]</arg>
       <arg>i[mmediate]</arg>
     </group>
   </arg>
   <sbr>
   <command>pg_ctl</command>
   <arg choice="plain">restart</arg>
   <arg>-w</arg>
49
   <arg>-s</arg>
50 51 52 53 54 55 56 57 58 59 60
   <arg>-D <replaceable>datadir</replaceable></arg>
   <arg>-m
     <group choice="plain">
       <arg>s[mart]</arg>
       <arg>f[ast]</arg>
       <arg>i[mmediate]</arg>
     </group>
   </arg>
   <arg>-o <replaceable>options</replaceable></arg>
   <sbr>
   <command>pg_ctl</command>
61 62 63 64 65
   <arg choice="plain">reload</arg>
   <arg>-s</arg>
   <arg>-D <replaceable>datadir</replaceable></arg>
   <sbr>
   <command>pg_ctl</command>
66 67
   <arg choice="plain">status</arg>
   <arg>-D <replaceable>datadir</replaceable></arg>
68 69 70 71 72
   <sbr>
   <command>pg_ctl</command>
   <arg choice="plain">kill</arg>
   <arg><replaceable>signal_name</replaceable></arg>
   <arg><replaceable>process_id</replaceable></arg>
73 74 75 76 77 78 79 80
  </cmdsynopsis>
 </refsynopsisdiv>


 <refsect1 id="app-pg-ctl-description">
  <title>Description</title>
  <para>
   <application>pg_ctl</application> is a utility for starting,
81 82 83 84 85 86
   stopping, or restarting the <productname>PostgreSQL</productname>
   backend server (<xref linkend="app-postmaster">), or displaying the
   status of a running server.  Although the server can be started
   manually, <application>pg_ctl</application> encapsulates tasks such
   as redirecting log output and properly detaching from the terminal
   and process group. It also provides convenient options for
Peter Eisentraut's avatar
Peter Eisentraut committed
87
   controlled shutdown.
88 89 90
  </para>

  <para>
91
   In <option>start</option> mode, a new server is launched.  The
92
   server is started in the background, and standard input is attached to
93
   <filename>/dev/null</filename>.  The standard output and standard
94
   error are either appended to a log file (if the <option>-l</option>
95
   option is used), or redirected to <application>pg_ctl</application>'s 
96 97
   standard output (not standard error).  If no log file is chosen, the 
   standard output of <application>pg_ctl</application> should be redirected 
98 99 100 101
   to a file or piped to another process such as a log rotating program
   like <application>rotatelogs</>; otherwise the <command>postmaster</command> 
   will write its output to the controlling terminal (from the background) 
   and will not leave the shell's process group.
102 103 104
  </para>

  <para>
105
   In <option>stop</option> mode, the server that is running in
106 107 108 109
   the specified data directory is shut down.  Three different
   shutdown methods can be selected with the <option>-m</option>
   option: <quote>Smart</quote> mode waits for all the clients to
   disconnect.  This is the default.  <quote>Fast</quote> mode does
110 111
   not wait for clients to disconnect.  All active transactions are
   rolled back and clients are forcibly disconnected, then the
112
   server is shut down.  <quote>Immediate</quote> mode will abort
113 114
   all server processes without a clean shutdown.  This will lead to 
   a recovery run on restart.
115 116 117 118
  </para>

  <para>
   <option>restart</option> mode effectively executes a stop followed
119 120
   by a start.  This allows changing the <command>postmaster</command>
   command-line options.
121 122
  </para>

123
  <para>
124 125 126 127 128 129 130
   <option>reload</option> mode simply sends the
   <command>postmaster</command> process a <systemitem>SIGHUP</>
   signal, causing it to reread its configuration files
   (<filename>postgresql.conf</filename>,
   <filename>pg_hba.conf</filename>, etc.).  This allows changing of
   configuration-file options that do not require a complete restart
   to take effect.
131 132
  </para>

133
  <para>
134 135 136 137
   <option>status</option> mode checks whether a server is running in
   the specified data directory. If it is, the <acronym>PID</acronym>
   and the command line options that were used to invoke it are
   displayed.
138
  </para>
139 140 141

  <para>
   <option>kill</option> mode allows you to send a signal to a specified
142
    process.  This is particularly valuable for <productname>Microsoft Windows</>
143 144
    which does not have a <application>kill</> command.  Use 
    <literal>--help</> to see a list of supported signal names.
145
  </para>
146
 </refsect1>
147

148 149 150 151
 <refsect1 id="app-pg-ctl-options">
  <title>Options</title>

  <para>
152 153 154

    <variablelist>
     <varlistentry>
155
      <term><option>-D <replaceable class="parameter">datadir</replaceable></option></term>
156 157
      <listitem>
       <para>
158 159 160
	Specifies the file system location of the database files.  If
	this is omitted, the environment variable
	<envar>PGDATA</envar> is used.
161 162 163 164 165
       </para>
      </listitem>
     </varlistentry>

     <varlistentry>
166
      <term><option>-l <replaceable class="parameter">filename</replaceable></option></term>
167 168
      <listitem>
       <para>
169 170
        Append the server log output to
        <replaceable>filename</replaceable>.  If the file does not
171
        exist, it is created.  The <systemitem>umask</> is set to 077, so access to
172
        the log file from other users is disallowed by default.
173 174 175 176 177
       </para>
      </listitem>
     </varlistentry>

     <varlistentry>
178
      <term><option>-m <replaceable class="parameter">mode</replaceable></option></term>
179 180
      <listitem>
       <para>
181 182 183 184
	Specifies the shutdown mode.  <replaceable>mode</replaceable>
	may be <literal>smart</literal>, <literal>fast</literal>, or
	<literal>immediate</literal>, or the first letter of one of
	these three.
185 186 187 188 189
       </para>
      </listitem>
     </varlistentry>

     <varlistentry>
190
      <term><option>-o <replaceable class="parameter">options</replaceable></option></term>
191 192
      <listitem>
       <para>
193 194
        Specifies options to be passed directly to the
        <command>postmaster</command> command.
195 196
       </para>
       <para>
197
	The options are usually surrounded by single or double
198 199 200 201 202 203
	quotes to ensure that they are passed through as a group.
       </para>
      </listitem>
     </varlistentry>

     <varlistentry>
204
      <term><option>-p <replaceable class="parameter">path</replaceable></option></term>
205 206
      <listitem>
       <para>
207
	Specifies the location of the <filename>postmaster</filename>
208
	executable.  By default the <filename>postmaster</filename> executable is taken from the same
209
	directory as <command>pg_ctl</command>, or failing that, the hard-wired
210 211
	installation directory.  It is not necessary to use this
	option unless you are doing something unusual and get errors
212
	that the <filename>postmaster</filename> executable was not found.
213 214 215 216 217
       </para>
      </listitem>
     </varlistentry>

     <varlistentry>
218
      <term><option>-s</option></term>
219 220
      <listitem>
       <para>
Peter Eisentraut's avatar
Peter Eisentraut committed
221
        Only print errors, no informational messages.
222 223 224 225 226
       </para>
      </listitem>
     </varlistentry>

     <varlistentry>
227
      <term><option>-w</option></term>
228 229
      <listitem>
       <para>
Peter Eisentraut's avatar
Peter Eisentraut committed
230
	Wait for the start or shutdown to complete.  Times out after
231
	60 seconds.  This is the default for shutdowns. A successful 
Bruce Momjian's avatar
Bruce Momjian committed
232
        shutdown is indicated by removal of the <acronym>PID</acronym> 
233 234
        file. For starting up, a successful <command>psql -l</command> 
        indicates success. <command>pg_ctl</command> will attempt to 
235 236
        use the proper port for <application>psql</>. If the environment variable 
        <envar>PGPORT</envar> exists, that is used. Otherwise, it will see if a port 
237 238 239
        has been set in the <filename>postgresql.conf</filename> file. 
        If neither of those is used, it will use the default port that 
        <productname>PostgreSQL</productname> was compiled with 
240 241 242
        (5432 by default). When waiting, <command>pg_ctl</command> will
        return an accurate exit code based on the success of the startup 
	or shutdown.
243 244 245
       </para>
      </listitem>
     </varlistentry>
246 247

     <varlistentry>
248
      <term><option>-W</option></term>
249 250
      <listitem>
       <para>
Peter Eisentraut's avatar
Peter Eisentraut committed
251 252
        Do not wait for start or shutdown to complete.  This is the
        default for starts and restarts.
253 254 255
       </para>
      </listitem>
     </varlistentry>
256 257
    </variablelist>
   </para>
258 259 260 261 262
 </refsect1>


 <refsect1>
  <title>Environment</title>
263

264 265 266 267 268 269
  <variablelist>
   <varlistentry>
    <term><envar>PGDATA</envar></term>

    <listitem>
     <para>
270 271 272 273 274 275 276 277 278 279 280
      Default data directory location.
     </para>
    </listitem>
   </varlistentry>

   <varlistentry>
    <term><envar>PGPORT</envar></term>

    <listitem>
     <para>
      Default port for <xref linkend="app-psql"> (used by the -w option).
281 282 283 284 285 286 287 288 289 290 291 292 293
     </para>
    </listitem>
   </varlistentry>
  </variablelist>

  <para>
   For others, see <xref linkend="app-postmaster">.
  </para>
 </refsect1>


 <refsect1>
  <title>Files</title>
294

295 296 297 298 299
  <variablelist>
   <varlistentry>
    <term><filename>postmaster.pid</filename></term>

    <listitem>
300 301 302 303
     <para>
      The existence of this file in the data directory is used to help
      <application>pg_ctl</application> determine if the server is
      currently running or not.
304 305 306 307 308 309 310 311
     </para>
    </listitem>
   </varlistentry>

   <varlistentry>
    <term><filename>postmaster.opts.default</filename></term>

    <listitem>
312 313 314 315 316 317
     <para>
      If this file exists in the data directory,
      <application>pg_ctl</application> (in <option>start</option>
      mode) will pass the contents of the file as options to the
      <command>postmaster</command> command, unless overridden by the
      <option>-o</option> option.
318 319 320 321 322 323 324 325 326 327 328 329 330 331 332 333 334 335 336 337 338 339
     </para>
    </listitem>
   </varlistentry>

   <varlistentry>
    <term><filename>postmaster.opts</filename></term>

    <listitem>
     <para>If this file exists in the data directory,
      <application>pg_ctl</application> (in <option>restart</option> mode) 
      will pass the contents of the file as options to the 
      <application>postmaster</application>, unless overridden 
      by the <option>-o</option> option. The contents of this file 
      are also displayed in <option>status</option> mode.
     </para>
    </listitem>
   </varlistentry>

   <varlistentry>
    <term><filename>postgresql.conf</filename></term>

    <listitem>
340 341 342 343
     <para>
      This file, located in the data directory, is parsed to find the
      proper port to use with <application>psql</application> when the
      <option>-w</option> is given in <option>start</option> mode.
344 345 346 347 348
     </para>
    </listitem>
   </varlistentry>

  </variablelist>
349 350
 </refsect1>

351

352 353 354 355 356 357
 <refsect1>
  <title>Notes</title>

  <para>
   Waiting for complete start is not a well-defined operation and may
   fail if access control is set up so that a local client cannot
358
   connect without manual interaction (e.g., password authentication).
359
  </para>
360 361
 </refsect1>

362

363
 <refsect1 id="R1-APP-PGCTL-2">
364
  <title>Examples</title>
365 366

  <refsect2 id="R2-APP-PGCTL-3">
367
   <title>Starting the Server</title>
368 369

   <para>
370
    To start up a server:
371 372 373
<screen>
<prompt>$</prompt> <userinput>pg_ctl start</userinput>
</screen>
374 375 376
   </para>

   <para>
377 378
    An example of starting the server, blocking until the server has
    come up is:
379 380 381
<screen>
<prompt>$</prompt> <userinput>pg_ctl -w start</userinput>
</screen>
382 383 384
   </para>

   <para>
385
    For a server using port 5433, and
386
    running without <function>fsync</function>, use:
387 388 389
<screen>
<prompt>$</prompt> <userinput>pg_ctl -o "-F -p 5433" start</userinput>
</screen>
390 391 392 393
   </para>
  </refsect2>

  <refsect2 id="R2-APP-PGCTL-4">
394
   <title>Stopping the Server</title>
395
   <para>
396 397 398
<screen>
<prompt>$</prompt> <userinput>pg_ctl stop</userinput>
</screen>
399
    stops the server. Using the <option>-m</option> switch allows one
400 401 402 403 404
    to control <emphasis>how</emphasis> the backend shuts down.
   </para>
  </refsect2>

  <refsect2 id="R2-APP-PGCTL-5">
405
   <title>Restarting the Server</title>
406 407

   <para>
408 409
    Restarting the server is almost equivalent to stopping the
    server and starting it again
410
    except that <command>pg_ctl</command> saves and reuses the command line options that
411
    were passed to the previously running instance.  To restart
412
    the server in the simplest form, use:
413 414 415
<screen>
<prompt>$</prompt> <userinput>pg_ctl restart</userinput>
</screen>
416 417 418
   </para>

   <para>
419
    To restart server,
420
    waiting for it to shut down and to come up:
421 422 423
<screen>
<prompt>$</prompt> <userinput>pg_ctl -w restart</userinput>
</screen>
424 425 426
   </para>

   <para>
427
    To restart using port 5433 and disabling <function>fsync</> after restarting:
428 429 430
<screen>
<prompt>$</prompt> <userinput>pg_ctl -o "-F -p 5433" restart</userinput>
</screen>
431 432 433 434
   </para>
  </refsect2>

  <refsect2 id="R2-APP-PGCTL-6">
435
   <title>Showing the Server Status</title>
436 437

   <para>
438 439 440 441 442
    Here is a sample status output from
    <application>pg_ctl</application>:
<screen>
<prompt>$</prompt> <userinput>pg_ctl status</userinput>
<computeroutput>
443
pg_ctl: postmaster is running (pid: 13718)
444 445 446 447 448
Command line was:
/usr/local/pgsql/bin/postmaster '-D' '/usr/local/pgsql/data' '-p' '5433' '-B' '128'
</computeroutput>
</screen>
    This is the command line that would be invoked in restart mode.
449 450 451
   </para>
  </refsect2>
 </refsect1>
452 453 454 455 456 457


 <refsect1>
  <title>See Also</title>

  <para>
458
   <xref linkend="app-postmaster">
459 460 461
  </para>
 </refsect1>

462 463 464 465 466 467 468 469 470 471 472 473 474 475 476 477 478 479
</refentry>

<!-- Keep this comment at the end of the file
Local variables:
mode:sgml
sgml-omittag:nil
sgml-shorttag:t
sgml-minimize-attributes:nil
sgml-always-quote-attributes:t
sgml-indent-step:1
sgml-indent-data:t
sgml-parent-document:nil
sgml-default-dtd-file:"../reference.ced"
sgml-exposed-tags:nil
sgml-local-catalogs:("/usr/lib/sgml/catalog")
sgml-local-ecat-files:nil
End:
-->