2 $Header: /cvsroot/pgsql/doc/src/sgml/ref/pg_ctl-ref.sgml,v 1.7 2001/04/27 01:31:56 momjian 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>Starts, stops, or restarts postmaster</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">status</arg>
62 <arg>-D <replaceable>datadir</replaceable></arg>
67 <refsect1 id="app-pg-ctl-description">
68 <title>Description</title>
70 <application>pg_ctl</application> is a utility for starting,
71 stopping, or restarting <xref linkend="app-postmaster">, the
72 <productname>PostgreSQL</productname> backend server, or displaying
73 the status of a running postmaster. Although the postmaster can be
74 started manually, <application>pg_ctl</application> encapulates
75 tasks such as redirecting log output, properly detaching from the
76 terminal and process group, and additionally provides an option for
81 In <option>start</option> mode, a new postmaster is launched. The
82 server is started in the background, the standard input attached to
83 <filename>/dev/null</filename>. The standard output and standard
84 error are either appended to a log file, if the <option>-l</option>
85 option is used, or are redirected to
86 <application>pg_ctl</application>'s standard output (not standard
87 error). If no log file is chosen, the standard output of
88 <application>pg_ctl</application> should be redirected to a file or
89 piped to another process, for example a log rotating program,
90 otherwise the postmaster will write its output the the controlling
91 terminal (from the background) and will not leave the shell's
96 In <option>stop</option> mode, the postmaster that is running on
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 will
102 be rolled back. <quote>Immediate</quote> mode will abort without
103 complete shutdown. This will lead to a recovery run on restart.
104 By the default, stop mode waits for the shutdown to complete.
108 <option>restart</option> mode effectively executes a stop followed
109 by a start. This allows the changing of postmaster command line
114 <option>status</option> mode checks whether a postmaster is running
115 and if so displays the <acronym>PID</acronym> and the command line
116 options that were used to invoke it.
119 <refsect2 id="app-pg-ctl-options">
120 <title>Options</title>
125 <term>-D <replaceable class="parameter">datadir</replaceable></term>
128 Specifies the file system location of the database files. If
129 this is omitted, the environment variable
130 <envar>PGDATA</envar> is used.
136 <term>-l <replaceable class="parameter">filename</replaceable></term>
139 Append the server log output to
140 <replaceable>filename</replaceable>. If the file does not
141 exist, it is created. The umask is set to 077, so access to
142 the log file from other users is disallowed by default.
148 <term>-m <replaceable class="parameter">mode</replaceable></term>
151 Specifies the shutdown mode. <replaceable>mode</replaceable>
152 may be <literal>smart</literal>, <literal>fast</literal>, or
153 <literal>immediate</literal>, or the first letter of one of
160 <term>-o <replaceable class="parameter">options</replaceable></term>
163 Specifies options to be passed directly to
164 <application>postmaster</application>.
167 The parameters are usually surrounded by single or double
168 quotes to ensure that they are passed through as a group.
174 <term>-p <replaceable class="parameter">path</replaceable></term>
177 Specifies the location of the <filename>postmaster</filename>
178 executable. By default the postmaster is taken from the same
179 directory as pg_ctl, or failing that, the hard-wired
180 installation directory. It is not necessary to use this
181 option unless you are doing something unusual and get errors
182 that the postmaster was not found.
191 Wait for the start or stutdown to complete. Times out after
192 60 seconds. This is the default for shutdowns.
201 Do not wait for start or shutdown to complete. This is the
202 default for starts and restarts.
211 Only print errors, no informational messages.
223 If the file <filename>postmaster.opts.default</filename> exists in
224 the data directory, the contents of the file will be passed as
225 options to the <application>postmaster</application>, unless
226 overridden by the <option>-o</option> option.
233 <refsect1 id="R1-APP-PGCTL-2">
234 <title>Examples</title>
236 <refsect2 id="R2-APP-PGCTL-3">
237 <title>Starting the postmaster</title>
240 To start up <application>postmaster</application>:
242 <prompt>$</prompt> <userinput>pg_ctl start</userinput>
247 An example of starting the <application>postmaster</application>,
248 blocking until postmaster comes up is:
250 <prompt>$</prompt> <userinput>pg_ctl -w start</userinput>
255 For a <application>postmaster</application> using port 5433, and
256 running without <function>fsync</function>, use:
258 <prompt>$</prompt> <userinput>pg_ctl -o "-F -p 5433" start</userinput>
263 <refsect2 id="R2-APP-PGCTL-4">
264 <title>Stopping the postmaster</title>
267 <prompt>$</prompt> <userinput>pg_ctl stop</userinput>
269 stops postmaster. Using the <option>-m</option> switch allows one
270 to control <emphasis>how</emphasis> the backend shuts down.
274 <refsect2 id="R2-APP-PGCTL-5">
275 <title>Restarting the postmaster</title>
278 This is almost equivalent to stopping the
279 <application>postmaster</application> then starting it again
280 except that pg_ctl saves and reuses the command line options that
281 were passed to the previously running instance. To restart
282 <application>postmaster</application> in the simplest form:
284 <prompt>$</prompt> <userinput>pg_ctl restart</userinput>
289 To restart <application>postmaster</application>,
290 waiting for it to shut down and to come up:
292 <prompt>$</prompt> <userinput>pg_ctl -w restart</userinput>
297 To restart using port 5433 and disabling fsync after restarting:
299 <prompt>$</prompt> <userinput>pg_ctl -o "-F -p 5433" restart</userinput>
304 <refsect2 id="R2-APP-PGCTL-6">
305 <title>Showing postmaster status</title>
308 Here is a sample status output from
309 <application>pg_ctl</application>:
311 <prompt>$</prompt> <userinput>pg_ctl status</userinput>
313 pg_ctl: postmaster is running (pid: 13718)
315 /usr/local/pgsql/bin/postmaster '-D' '/usr/local/pgsql/data' '-p' '5433' '-B' '128'
318 This is the command line that would be invoked in restart mode.
327 Waiting for complete start is not a well-defined operation and may
328 fail if access control is set up in way that a local client cannot
329 connect without manual interaction. It should be avoided.
334 <title>See Also</title>
337 <xref linkend="app-postmaster">, <citetitle>PostgreSQL Administrator's Guide</citetitle>
343 <!-- Keep this comment at the end of the file
348 sgml-minimize-attributes:nil
349 sgml-always-quote-attributes:t
352 sgml-parent-document:nil
353 sgml-default-dtd-file:"../reference.ced"
354 sgml-exposed-tags:nil
355 sgml-local-catalogs:("/usr/lib/sgml/catalog")
356 sgml-local-ecat-files:nil