2 $Header: /cvsroot/pgsql/doc/src/sgml/ref/pg_ctl-ref.sgml,v 1.17 2002/10/11 23:03:48 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 <xref linkend="app-postmaster">, the
73 <productname>PostgreSQL</productname> backend server, or displaying
74 the status of a running postmaster. Although the postmaster can be
75 started manually, <application>pg_ctl</application> encapsulates
76 tasks such as redirecting log output, properly detaching from the
77 terminal and process group, and it provides convenient options for
82 In <option>start</option> mode, a new postmaster is launched. The
83 server is started in the background, the standard input 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 are redirected to
87 <application>pg_ctl</application>'s standard output (not standard
88 error). If no log file is chosen, the standard output of
89 <application>pg_ctl</application> should be redirected to a file or
90 piped to another process, for example a log rotating program,
91 otherwise the postmaster will write its output the the controlling
92 terminal (from the background) and will not leave the shell's
97 In <option>stop</option> mode, the postmaster that is running in
98 the specified data directory is shut down. Three different
99 shutdown methods can be selected with the <option>-m</option>
100 option: <quote>Smart</quote> mode waits for all the clients to
101 disconnect. This is the default. <quote>Fast</quote> mode does
102 not wait for clients to disconnect. All active transactions are
103 rolled back and clients are forcibly disconnected, then the
104 database is shut down. <quote>Immediate</quote> mode will abort
105 all server processes without clean shutdown. This will lead to a recovery
110 <option>restart</option> mode effectively executes a stop followed
111 by a start. This allows the changing of postmaster command line
116 <option>reload</option> mode simply sends the postmaster a <systemitem>SIGHUP</> signal,
117 causing it to reread its configuration files
118 (<filename>postgresql.conf</filename>, <filename>pg_hba.conf</filename>,
119 etc.). This allows changing of configuration-file options that do not
120 require a complete restart to take effect.
124 <option>status</option> mode checks whether a postmaster is running
125 and if so displays the <acronym>PID</acronym> and the command line
126 options that were used to invoke it.
130 <refsect1 id="app-pg-ctl-options">
131 <title>Options</title>
137 <term>-D <replaceable class="parameter">datadir</replaceable></term>
140 Specifies the file system location of the database files. If
141 this is omitted, the environment variable
142 <envar>PGDATA</envar> is used.
148 <term>-l <replaceable class="parameter">filename</replaceable></term>
151 Append the server log output to
152 <replaceable>filename</replaceable>. If the file does not
153 exist, it is created. The <systemitem>umask</> is set to 077, so access to
154 the log file from other users is disallowed by default.
160 <term>-m <replaceable class="parameter">mode</replaceable></term>
163 Specifies the shutdown mode. <replaceable>mode</replaceable>
164 may be <literal>smart</literal>, <literal>fast</literal>, or
165 <literal>immediate</literal>, or the first letter of one of
172 <term>-o <replaceable class="parameter">options</replaceable></term>
175 Specifies options to be passed directly to
176 <application>postmaster</application>.
179 The parameters are usually surrounded by single or double
180 quotes to ensure that they are passed through as a group.
186 <term>-p <replaceable class="parameter">path</replaceable></term>
189 Specifies the location of the <filename>postmaster</filename>
190 executable. By default the postmaster is taken from the same
191 directory as <command>pg_ctl</>, or failing that, the hard-wired
192 installation directory. It is not necessary to use this
193 option unless you are doing something unusual and get errors
194 that the postmaster was not found.
203 Only print errors, no informational messages.
212 Wait for the start or shutdown to complete. Times out after
213 60 seconds. This is the default for shutdowns.
222 Do not wait for start or shutdown to complete. This is the
223 default for starts and restarts.
233 <title>Environment</title>
237 <term><envar>PGDATA</envar></term>
241 Default data direction location
248 For others, see <xref linkend="app-postmaster">.
257 If the file <filename>postmaster.opts.default</filename> exists in
258 the data directory, the contents of the file will be passed as
259 options to the <application>postmaster</application>, unless
260 overridden by the <option>-o</option> option.
269 Waiting for complete start is not a well-defined operation and may
270 fail if access control is set up so that a local client cannot
271 connect without manual interaction. It should be avoided.
276 <refsect1 id="R1-APP-PGCTL-2">
277 <title>Examples</title>
279 <refsect2 id="R2-APP-PGCTL-3">
280 <title>Starting the postmaster</title>
283 To start up a <application>postmaster</application>:
285 <prompt>$</prompt> <userinput>pg_ctl start</userinput>
290 An example of starting the <application>postmaster</application>,
291 blocking until the postmaster comes up is:
293 <prompt>$</prompt> <userinput>pg_ctl -w start</userinput>
298 For a <application>postmaster</application> using port 5433, and
299 running without <function>fsync</function>, use:
301 <prompt>$</prompt> <userinput>pg_ctl -o "-F -p 5433" start</userinput>
306 <refsect2 id="R2-APP-PGCTL-4">
307 <title>Stopping the postmaster</title>
310 <prompt>$</prompt> <userinput>pg_ctl stop</userinput>
312 stops the postmaster. Using the <option>-m</option> switch allows one
313 to control <emphasis>how</emphasis> the backend shuts down.
317 <refsect2 id="R2-APP-PGCTL-5">
318 <title>Restarting the postmaster</title>
321 This is almost equivalent to stopping the
322 <application>postmaster</application> and starting it again
323 except that <command>pg_ctl</command> saves and reuses the command line options that
324 were passed to the previously running instance. To restart
325 the <application>postmaster</application> in the simplest form:
327 <prompt>$</prompt> <userinput>pg_ctl restart</userinput>
332 To restart <application>postmaster</application>,
333 waiting for it to shut down and to come up:
335 <prompt>$</prompt> <userinput>pg_ctl -w restart</userinput>
340 To restart using port 5433 and disabling <function>fsync</> after restarting:
342 <prompt>$</prompt> <userinput>pg_ctl -o "-F -p 5433" restart</userinput>
347 <refsect2 id="R2-APP-PGCTL-6">
348 <title>Showing postmaster status</title>
351 Here is a sample status output from
352 <application>pg_ctl</application>:
354 <prompt>$</prompt> <userinput>pg_ctl status</userinput>
356 pg_ctl: postmaster is running (pid: 13718)
358 /usr/local/pgsql/bin/postmaster '-D' '/usr/local/pgsql/data' '-p' '5433' '-B' '128'
361 This is the command line that would be invoked in restart mode.
368 <title>See Also</title>
371 <xref linkend="app-postmaster">, <citetitle>PostgreSQL Administrator's Guide</citetitle>
377 <!-- Keep this comment at the end of the file
382 sgml-minimize-attributes:nil
383 sgml-always-quote-attributes:t
386 sgml-parent-document:nil
387 sgml-default-dtd-file:"../reference.ced"
388 sgml-exposed-tags:nil
389 sgml-local-catalogs:("/usr/lib/sgml/catalog")
390 sgml-local-ecat-files:nil