2 $Header: /cvsroot/pgsql/doc/src/sgml/ref/pg_ctl-ref.sgml,v 1.10 2001/11/19 03:58:25 tgl Exp $
6 <refentry id="app-pg-ctl">
8 <date>2001-02-08</date>
12 <refentrytitle id="app-pg-ctl-title"><application>pg_ctl</application></refentrytitle>
13 <manvolnum>1</manvolnum>
14 <refmiscinfo>Application</refmiscinfo>
18 <refname>pg_ctl</refname>
19 <refpurpose>start, stop, or restart a <productname>PostgreSQL</productname> server</refpurpose>
24 <command>pg_ctl</command>
25 <arg choice="plain">start</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>
33 <command>pg_ctl</command>
34 <arg choice="plain">stop</arg>
37 <arg>-D <replaceable>datadir</replaceable></arg>
39 <group choice="plain">
42 <arg>i[mmediate]</arg>
46 <command>pg_ctl</command>
47 <arg choice="plain">restart</arg>
50 <arg>-D <replaceable>datadir</replaceable></arg>
52 <group choice="plain">
55 <arg>i[mmediate]</arg>
58 <arg>-o <replaceable>options</replaceable></arg>
60 <command>pg_ctl</command>
61 <arg choice="plain">reload</arg>
63 <arg>-D <replaceable>datadir</replaceable></arg>
65 <command>pg_ctl</command>
66 <arg choice="plain">status</arg>
67 <arg>-D <replaceable>datadir</replaceable></arg>
72 <refsect1 id="app-pg-ctl-description">
73 <title>Description</title>
75 <application>pg_ctl</application> is a utility for starting,
76 stopping, or restarting <xref linkend="app-postmaster">, the
77 <productname>PostgreSQL</productname> backend server, or displaying
78 the status of a running postmaster. Although the postmaster can be
79 started manually, <application>pg_ctl</application> encapulates
80 tasks such as redirecting log output, properly detaching from the
81 terminal and process group, and it provides convenient options for
86 In <option>start</option> mode, a new postmaster is launched. The
87 server is started in the background, the standard input attached to
88 <filename>/dev/null</filename>. The standard output and standard
89 error are either appended to a log file, if the <option>-l</option>
90 option is used, or are redirected to
91 <application>pg_ctl</application>'s standard output (not standard
92 error). If no log file is chosen, the standard output of
93 <application>pg_ctl</application> should be redirected to a file or
94 piped to another process, for example a log rotating program,
95 otherwise the postmaster will write its output the the controlling
96 terminal (from the background) and will not leave the shell's
101 In <option>stop</option> mode, the postmaster that is running in
102 the specified data directory is shut down. Three different
103 shutdown methods can be selected with the <option>-m</option>
104 option: <quote>Smart</quote> mode waits for all the clients to
105 disconnect. This is the default. <quote>Fast</quote> mode does
106 not wait for clients to disconnect. All active transactions are
107 rolled back and clients are forcibly disconnected, then the
108 database is shut down. <quote>Immediate</quote> mode will abort
109 all server processes without clean shutdown. This will lead to a recovery
114 <option>restart</option> mode effectively executes a stop followed
115 by a start. This allows the changing of postmaster command line
120 <option>reload</option> mode simply sends the postmaster a SIGHUP signal,
121 causing it to reread its configuration files
122 (<filename>postgresql.conf</filename>, <filename>pg_hba.conf</filename>,
123 etc). This allows changing of configuration-file options that do not
124 require a complete restart to take effect.
128 <option>status</option> mode checks whether a postmaster is running
129 and if so displays the <acronym>PID</acronym> and the command line
130 options that were used to invoke it.
133 <refsect2 id="app-pg-ctl-options">
134 <title>Options</title>
139 <term>-D <replaceable class="parameter">datadir</replaceable></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>-l <replaceable class="parameter">filename</replaceable></term>
153 Append the server log output to
154 <replaceable>filename</replaceable>. If the file does not
155 exist, it is created. The umask is set to 077, so access to
156 the log file from other users is disallowed by default.
162 <term>-m <replaceable class="parameter">mode</replaceable></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>-o <replaceable class="parameter">options</replaceable></term>
177 Specifies options to be passed directly to
178 <application>postmaster</application>.
181 The parameters are usually surrounded by single or double
182 quotes to ensure that they are passed through as a group.
188 <term>-p <replaceable class="parameter">path</replaceable></term>
191 Specifies the location of the <filename>postmaster</filename>
192 executable. By default the postmaster is taken from the same
193 directory as pg_ctl, 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 postmaster was not found.
205 Wait for the start or shutdown to complete. Times out after
206 60 seconds. This is the default for shutdowns.
215 Do not wait for start or shutdown to complete. This is the
216 default for starts and restarts.
225 Only print errors, no informational messages.
237 If the file <filename>postmaster.opts.default</filename> exists in
238 the data directory, the contents of the file will be passed as
239 options to the <application>postmaster</application>, unless
240 overridden by the <option>-o</option> option.
247 <refsect1 id="R1-APP-PGCTL-2">
248 <title>Examples</title>
250 <refsect2 id="R2-APP-PGCTL-3">
251 <title>Starting the postmaster</title>
254 To start up <application>postmaster</application>:
256 <prompt>$</prompt> <userinput>pg_ctl start</userinput>
261 An example of starting the <application>postmaster</application>,
262 blocking until postmaster comes up is:
264 <prompt>$</prompt> <userinput>pg_ctl -w start</userinput>
269 For a <application>postmaster</application> using port 5433, and
270 running without <function>fsync</function>, use:
272 <prompt>$</prompt> <userinput>pg_ctl -o "-F -p 5433" start</userinput>
277 <refsect2 id="R2-APP-PGCTL-4">
278 <title>Stopping the postmaster</title>
281 <prompt>$</prompt> <userinput>pg_ctl stop</userinput>
283 stops postmaster. Using the <option>-m</option> switch allows one
284 to control <emphasis>how</emphasis> the backend shuts down.
288 <refsect2 id="R2-APP-PGCTL-5">
289 <title>Restarting the postmaster</title>
292 This is almost equivalent to stopping the
293 <application>postmaster</application> then starting it again
294 except that pg_ctl saves and reuses the command line options that
295 were passed to the previously running instance. To restart
296 <application>postmaster</application> in the simplest form:
298 <prompt>$</prompt> <userinput>pg_ctl restart</userinput>
303 To restart <application>postmaster</application>,
304 waiting for it to shut down and to come up:
306 <prompt>$</prompt> <userinput>pg_ctl -w restart</userinput>
311 To restart using port 5433 and disabling fsync after restarting:
313 <prompt>$</prompt> <userinput>pg_ctl -o "-F -p 5433" restart</userinput>
318 <refsect2 id="R2-APP-PGCTL-6">
319 <title>Showing postmaster status</title>
322 Here is a sample status output from
323 <application>pg_ctl</application>:
325 <prompt>$</prompt> <userinput>pg_ctl status</userinput>
327 pg_ctl: postmaster is running (pid: 13718)
329 /usr/local/pgsql/bin/postmaster '-D' '/usr/local/pgsql/data' '-p' '5433' '-B' '128'
332 This is the command line that would be invoked in restart mode.
341 Waiting for complete start is not a well-defined operation and may
342 fail if access control is set up so that a local client cannot
343 connect without manual interaction. It should be avoided.
348 <title>See Also</title>
351 <xref linkend="app-postmaster">, <citetitle>PostgreSQL Administrator's Guide</citetitle>
357 <!-- Keep this comment at the end of the file
362 sgml-minimize-attributes:nil
363 sgml-always-quote-attributes:t
366 sgml-parent-document:nil
367 sgml-default-dtd-file:"../reference.ced"
368 sgml-exposed-tags:nil
369 sgml-local-catalogs:("/usr/lib/sgml/catalog")
370 sgml-local-ecat-files:nil