2 $Header: /cvsroot/pgsql/doc/src/sgml/ref/pg_ctl-ref.sgml,v 1.22 2003/03/25 16:15:42 petere Exp $
3 PostgreSQL documentation
6 <refentry id="app-pg-ctl">
8 <refentrytitle id="app-pg-ctl-title"><application>pg_ctl</application></refentrytitle>
9 <manvolnum>1</manvolnum>
10 <refmiscinfo>Application</refmiscinfo>
14 <refname>pg_ctl</refname>
15 <refpurpose>start, stop, or restart a <productname>PostgreSQL</productname> server</refpurpose>
20 <command>pg_ctl</command>
21 <arg choice="plain">start</arg>
24 <arg>-D <replaceable>datadir</replaceable></arg>
25 <arg>-l <replaceable>filename</replaceable></arg>
26 <arg>-o <replaceable>options</replaceable></arg>
27 <arg>-p <replaceable>path</replaceable></arg>
29 <command>pg_ctl</command>
30 <arg choice="plain">stop</arg>
33 <arg>-D <replaceable>datadir</replaceable></arg>
35 <group choice="plain">
38 <arg>i[mmediate]</arg>
42 <command>pg_ctl</command>
43 <arg choice="plain">restart</arg>
46 <arg>-D <replaceable>datadir</replaceable></arg>
48 <group choice="plain">
51 <arg>i[mmediate]</arg>
54 <arg>-o <replaceable>options</replaceable></arg>
56 <command>pg_ctl</command>
57 <arg choice="plain">reload</arg>
59 <arg>-D <replaceable>datadir</replaceable></arg>
61 <command>pg_ctl</command>
62 <arg choice="plain">status</arg>
63 <arg>-D <replaceable>datadir</replaceable></arg>
68 <refsect1 id="app-pg-ctl-description">
69 <title>Description</title>
71 <application>pg_ctl</application> is a utility for starting,
72 stopping, or restarting the <productname>PostgreSQL</productname>
73 backend server (<xref linkend="app-postmaster">), or displaying the
74 status of a running server. Although the server can be started
75 manually, <application>pg_ctl</application> encapsulates tasks such
76 as redirecting log output and properly detaching from the terminal
77 and process group. It also provides convenient options for
82 In <option>start</option> mode, a new server is launched. The
83 server is started in the background, and standard input is attached to
84 <filename>/dev/null</filename>. The standard output and standard
85 error are either appended to a log file (if the <option>-l</option>
86 option is used), or redirected to <application>pg_ctl</application>'s
87 standard output (not standard error). If no log file is chosen, the
88 standard output of <application>pg_ctl</application> should be redirected
89 to a file or piped to another process, for example a log rotating program,
90 otherwise <command>postmaster</command> will write its output to the controlling
91 terminal (from the background) and will not leave the shell's
96 In <option>stop</option> mode, the server that is running in
97 the specified data directory is shut down. Three different
98 shutdown methods can be selected with the <option>-m</option>
99 option: <quote>Smart</quote> mode waits for all the clients to
100 disconnect. This is the default. <quote>Fast</quote> mode does
101 not wait for clients to disconnect. All active transactions are
102 rolled back and clients are forcibly disconnected, then the
103 server is shut down. <quote>Immediate</quote> mode will abort
104 all server processes without a clean shutdown. This will lead to
105 a recovery run on restart.
109 <option>restart</option> mode effectively executes a stop followed
110 by a start. This allows changing the <command>postmaster</command>
111 command-line options.
115 <option>reload</option> mode simply sends the
116 <command>postmaster</command> process a <systemitem>SIGHUP</>
117 signal, causing it to reread its configuration files
118 (<filename>postgresql.conf</filename>,
119 <filename>pg_hba.conf</filename>, etc.). This allows changing of
120 configuration-file options that do not require a complete restart
125 <option>status</option> mode checks whether a server is running in
126 the specified data directory. If it is, the <acronym>PID</acronym>
127 and the command line options that were used to invoke it are
132 <refsect1 id="app-pg-ctl-options">
133 <title>Options</title>
139 <term><option>-D <replaceable class="parameter">datadir</replaceable></option></term>
142 Specifies the file system location of the database files. If
143 this is omitted, the environment variable
144 <envar>PGDATA</envar> is used.
150 <term><option>-l <replaceable class="parameter">filename</replaceable></option></term>
153 Append the server log output to
154 <replaceable>filename</replaceable>. If the file does not
155 exist, it is created. The <systemitem>umask</> is set to 077, so access to
156 the log file from other users is disallowed by default.
162 <term><option>-m <replaceable class="parameter">mode</replaceable></option></term>
165 Specifies the shutdown mode. <replaceable>mode</replaceable>
166 may be <literal>smart</literal>, <literal>fast</literal>, or
167 <literal>immediate</literal>, or the first letter of one of
174 <term><option>-o <replaceable class="parameter">options</replaceable></option></term>
177 Specifies options to be passed directly to the
178 <command>postmaster</command> command.
181 The options are usually surrounded by single or double
182 quotes to ensure that they are passed through as a group.
188 <term><option>-p <replaceable class="parameter">path</replaceable></option></term>
191 Specifies the location of the <filename>postmaster</filename>
192 executable. By default the <filename>postmaster</filename> executable is taken from the same
193 directory as <command>pg_ctl</command>, or failing that, the hard-wired
194 installation directory. It is not necessary to use this
195 option unless you are doing something unusual and get errors
196 that the <filename>postmaster</filename> executable was not found.
202 <term><option>-s</option></term>
205 Only print errors, no informational messages.
211 <term><option>-w</option></term>
214 Wait for the start or shutdown to complete. Times out after
215 60 seconds. This is the default for shutdowns. A successful
216 shutdown is indicated by removal of the <acronym>PID</acronym>
217 file. For starting up, a successful <command>psql -l</command>
218 indicates success. <command>pg_ctl</command> will attempt to
219 use the proper port for psql. If the environment variable
220 PGPORT exists, that is used. Otherwise, it will see if a port
221 has been set in the <filename>postgresql.conf</filename> file.
222 If neither of those is used, it will use the default port that
223 <productname>PostgreSQL</productname> was compiled with
230 <term><option>-W</option></term>
233 Do not wait for start or shutdown to complete. This is the
234 default for starts and restarts.
244 <title>Environment</title>
248 <term><envar>PGDATA</envar></term>
252 Default data directory location.
258 <term><envar>PGPORT</envar></term>
262 Default port for <xref linkend="app-psql"> (used by the -w option).
269 For others, see <xref linkend="app-postmaster">.
279 <term><filename>postmaster.pid</filename></term>
283 The existence of this file in the data directory is used to help
284 <application>pg_ctl</application> determine if the server is
285 currently running or not.
291 <term><filename>postmaster.opts.default</filename></term>
295 If this file exists in the data directory,
296 <application>pg_ctl</application> (in <option>start</option>
297 mode) will pass the contents of the file as options to the
298 <command>postmaster</command> command, unless overridden by the
299 <option>-o</option> option.
305 <term><filename>postmaster.opts</filename></term>
308 <para>If this file exists in the data directory,
309 <application>pg_ctl</application> (in <option>restart</option> mode)
310 will pass the contents of the file as options to the
311 <application>postmaster</application>, unless overridden
312 by the <option>-o</option> option. The contents of this file
313 are also displayed in <option>status</option> mode.
319 <term><filename>postgresql.conf</filename></term>
323 This file, located in the data directory, is parsed to find the
324 proper port to use with <application>psql</application> when the
325 <option>-w</option> is given in <option>start</option> mode.
338 Waiting for complete start is not a well-defined operation and may
339 fail if access control is set up so that a local client cannot
340 connect without manual interaction (e.g., password authentication).
345 <refsect1 id="R1-APP-PGCTL-2">
346 <title>Examples</title>
348 <refsect2 id="R2-APP-PGCTL-3">
349 <title>Starting the Server</title>
352 To start up a server:
354 <prompt>$</prompt> <userinput>pg_ctl start</userinput>
359 An example of starting the server, blocking until the server has
362 <prompt>$</prompt> <userinput>pg_ctl -w start</userinput>
367 For a server using port 5433, and
368 running without <function>fsync</function>, use:
370 <prompt>$</prompt> <userinput>pg_ctl -o "-F -p 5433" start</userinput>
375 <refsect2 id="R2-APP-PGCTL-4">
376 <title>Stopping the Server</title>
379 <prompt>$</prompt> <userinput>pg_ctl stop</userinput>
381 stops the server. Using the <option>-m</option> switch allows one
382 to control <emphasis>how</emphasis> the backend shuts down.
386 <refsect2 id="R2-APP-PGCTL-5">
387 <title>Restarting the Server</title>
390 Restarting the server is almost equivalent to stopping the
391 server and starting it again
392 except that <command>pg_ctl</command> saves and reuses the command line options that
393 were passed to the previously running instance. To restart
394 the server in the simplest form, use:
396 <prompt>$</prompt> <userinput>pg_ctl restart</userinput>
402 waiting for it to shut down and to come up:
404 <prompt>$</prompt> <userinput>pg_ctl -w restart</userinput>
409 To restart using port 5433 and disabling <function>fsync</> after restarting:
411 <prompt>$</prompt> <userinput>pg_ctl -o "-F -p 5433" restart</userinput>
416 <refsect2 id="R2-APP-PGCTL-6">
417 <title>Showing the Server Status</title>
420 Here is a sample status output from
421 <application>pg_ctl</application>:
423 <prompt>$</prompt> <userinput>pg_ctl status</userinput>
425 pg_ctl: postmaster is running (pid: 13718)
427 /usr/local/pgsql/bin/postmaster '-D' '/usr/local/pgsql/data' '-p' '5433' '-B' '128'
430 This is the command line that would be invoked in restart mode.
437 <title>See Also</title>
440 <xref linkend="app-postmaster">
446 <!-- Keep this comment at the end of the file
451 sgml-minimize-attributes:nil
452 sgml-always-quote-attributes:t
455 sgml-parent-document:nil
456 sgml-default-dtd-file:"../reference.ced"
457 sgml-exposed-tags:nil
458 sgml-local-catalogs:("/usr/lib/sgml/catalog")
459 sgml-local-ecat-files:nil