2 $Header: /cvsroot/pgsql/doc/src/sgml/ref/pg_ctl-ref.sgml,v 1.14 2002/04/21 19:02:39 thomas 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.
129 <refsect2 id="app-pg-ctl-options">
130 <title>Options</title>
135 <term>-D <replaceable class="parameter">datadir</replaceable></term>
138 Specifies the file system location of the database files. If
139 this is omitted, the environment variable
140 <envar>PGDATA</envar> is used.
146 <term>-l <replaceable class="parameter">filename</replaceable></term>
149 Append the server log output to
150 <replaceable>filename</replaceable>. If the file does not
151 exist, it is created. The umask is set to 077, so access to
152 the log file from other users is disallowed by default.
158 <term>-m <replaceable class="parameter">mode</replaceable></term>
161 Specifies the shutdown mode. <replaceable>mode</replaceable>
162 may be <literal>smart</literal>, <literal>fast</literal>, or
163 <literal>immediate</literal>, or the first letter of one of
170 <term>-o <replaceable class="parameter">options</replaceable></term>
173 Specifies options to be passed directly to
174 <application>postmaster</application>.
177 The parameters are usually surrounded by single or double
178 quotes to ensure that they are passed through as a group.
184 <term>-p <replaceable class="parameter">path</replaceable></term>
187 Specifies the location of the <filename>postmaster</filename>
188 executable. By default the postmaster is taken from the same
189 directory as <command>pg_ctl</>, or failing that, the hard-wired
190 installation directory. It is not necessary to use this
191 option unless you are doing something unusual and get errors
192 that the postmaster was not found.
201 Only print errors, no informational messages.
210 Wait for the start or shutdown to complete. Times out after
211 60 seconds. This is the default for shutdowns.
220 Do not wait for start or shutdown to complete. This is the
221 default for starts and restarts.
233 If the file <filename>postmaster.opts.default</filename> exists in
234 the data directory, the contents of the file will be passed as
235 options to the <application>postmaster</application>, unless
236 overridden by the <option>-o</option> option.
243 <refsect1 id="R1-APP-PGCTL-2">
244 <title>Examples</title>
246 <refsect2 id="R2-APP-PGCTL-3">
247 <title>Starting the postmaster</title>
250 To start up a <application>postmaster</application>:
252 <prompt>$</prompt> <userinput>pg_ctl start</userinput>
257 An example of starting the <application>postmaster</application>,
258 blocking until the postmaster comes up is:
260 <prompt>$</prompt> <userinput>pg_ctl -w start</userinput>
265 For a <application>postmaster</application> using port 5433, and
266 running without <function>fsync</function>, use:
268 <prompt>$</prompt> <userinput>pg_ctl -o "-F -p 5433" start</userinput>
273 <refsect2 id="R2-APP-PGCTL-4">
274 <title>Stopping the postmaster</title>
277 <prompt>$</prompt> <userinput>pg_ctl stop</userinput>
279 stops the postmaster. Using the <option>-m</option> switch allows one
280 to control <emphasis>how</emphasis> the backend shuts down.
284 <refsect2 id="R2-APP-PGCTL-5">
285 <title>Restarting the postmaster</title>
288 This is almost equivalent to stopping the
289 <application>postmaster</application> and starting it again
290 except that <command>pg_ctl</command> saves and reuses the command line options that
291 were passed to the previously running instance. To restart
292 the <application>postmaster</application> in the simplest form:
294 <prompt>$</prompt> <userinput>pg_ctl restart</userinput>
299 To restart <application>postmaster</application>,
300 waiting for it to shut down and to come up:
302 <prompt>$</prompt> <userinput>pg_ctl -w restart</userinput>
307 To restart using port 5433 and disabling <function>fsync</> after restarting:
309 <prompt>$</prompt> <userinput>pg_ctl -o "-F -p 5433" restart</userinput>
314 <refsect2 id="R2-APP-PGCTL-6">
315 <title>Showing postmaster status</title>
318 Here is a sample status output from
319 <application>pg_ctl</application>:
321 <prompt>$</prompt> <userinput>pg_ctl status</userinput>
323 pg_ctl: postmaster is running (pid: 13718)
325 /usr/local/pgsql/bin/postmaster '-D' '/usr/local/pgsql/data' '-p' '5433' '-B' '128'
328 This is the command line that would be invoked in restart mode.
337 Waiting for complete start is not a well-defined operation and may
338 fail if access control is set up so that a local client cannot
339 connect without manual interaction. It should be avoided.
344 <title>See Also</title>
347 <xref linkend="app-postmaster">, <citetitle>PostgreSQL Administrator's Guide</citetitle>
353 <!-- Keep this comment at the end of the file
358 sgml-minimize-attributes:nil
359 sgml-always-quote-attributes:t
362 sgml-parent-document:nil
363 sgml-default-dtd-file:"../reference.ced"
364 sgml-exposed-tags:nil
365 sgml-local-catalogs:("/usr/lib/sgml/catalog")
366 sgml-local-ecat-files:nil