2 $Header: /cvsroot/pgsql/doc/src/sgml/ref/pg_ctl-ref.sgml,v 1.6 2001/02/08 19:39:24 petere 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>
27 <arg>-D <replaceable>datadir</replaceable></arg>
28 <arg>-l <replaceable>filename</replaceable></arg>
29 <arg>-o <replaceable>options</replaceable></arg>
30 <arg>-p <replaceable>path</replaceable></arg>
32 <command>pg_ctl</command>
33 <arg choice="plain">stop</arg>
35 <arg>-D <replaceable>datadir</replaceable></arg>
37 <group choice="plain">
40 <arg>i[mmediate]</arg>
44 <command>pg_ctl</command>
45 <arg choice="plain">restart</arg>
47 <arg>-D <replaceable>datadir</replaceable></arg>
49 <group choice="plain">
52 <arg>i[mmediate]</arg>
55 <arg>-o <replaceable>options</replaceable></arg>
57 <command>pg_ctl</command>
58 <arg choice="plain">status</arg>
59 <arg>-D <replaceable>datadir</replaceable></arg>
64 <refsect1 id="app-pg-ctl-description">
65 <title>Description</title>
67 <application>pg_ctl</application> is a utility for starting,
68 stopping, or restarting <xref linkend="app-postmaster">, the
69 <productname>PostgreSQL</productname> backend server, or displaying
70 the status of a running postmaster. Although the postmaster can be
71 started manually, <application>pg_ctl</application> encapulates
72 tasks such as redirecting log output, properly detaching from the
73 terminal and process group, and additionally provides an option for
78 In <option>start</option> mode, a new postmaster is launched. The
79 server is started in the background, the standard input attached to
80 <filename>/dev/null</filename>. The standard output and standard
81 error are either appended to a log file, if the <option>-l</option>
82 option is used, or are redirected to
83 <application>pg_ctl</application>'s standard output (not standard
84 error). If no log file is chosen, the standard output of
85 <application>pg_ctl</application> should be redirected to a file or
86 piped to another process, for example a log rotating program,
87 otherwise the postmaster will write its output the the controlling
88 terminal (from the background) and will not leave the shell's
93 In <option>stop</option> mode, the postmaster that is running on
94 the specified data directory is shut down. Three different
95 shutdown methods can be selected with the <option>-m</option>
96 option: <quote>Smart</quote> mode waits for all the clients to
97 disconnect. This is the default. <quote>Fast</quote> mode does
98 not wait for clients to disconnect. All active transactions will
99 be rolled back. <quote>Immediate</quote> mode will abort without
100 complete shutdown. This will lead to a recovery run on restart.
101 By the default, stop mode waits for the shutdown to complete.
105 <option>restart</option> mode effectively executes a stop followed
106 by a start. This allows the changing of postmaster command line
111 <option>status</option> mode checks whether a postmaster is running
112 and if so displays the <acronym>PID</acronym> and the command line
113 options that were used to invoke it.
116 <refsect2 id="app-pg-ctl-options">
117 <title>Options</title>
122 <term>-D <replaceable class="parameter">datadir</replaceable></term>
125 Specifies the file system location of the database files. If
126 this is omitted, the environment variable
127 <envar>PGDATA</envar> is used.
133 <term>-l <replaceable class="parameter">filename</replaceable></term>
136 Append the server log output to
137 <replaceable>filename</replaceable>. If the file does not
138 exist, it is created. The umask is set to 077, so access to
139 the log file from other users is disallowed by default.
145 <term>-m <replaceable class="parameter">mode</replaceable></term>
148 Specifies the shutdown mode. <replaceable>mode</replaceable>
149 may be <literal>smart</literal>, <literal>fast</literal>, or
150 <literal>immediate</literal>, or the first letter of one of
157 <term>-o <replaceable class="parameter">options</replaceable></term>
160 Specifies options to be passed directly to
161 <application>postmaster</application>.
164 The parameters are usually surrounded by single or double
165 quotes to ensure that they are passed through as a group.
171 <term>-p <replaceable class="parameter">path</replaceable></term>
174 Specifies the location of the <filename>postmaster</filename>
175 executable. By default the postmaster is taken from the same
176 directory as pg_ctl, or failing that, the hard-wired
177 installation directory. It is not necessary to use this
178 option unless you are doing something unusual and get errors
179 that the postmaster was not found.
188 Wait for the start or stutdown to complete. Times out after
189 60 seconds. This is the default for shutdowns.
198 Do not wait for start or shutdown to complete. This is the
199 default for starts and restarts.
211 If the file <filename>postmaster.opts.default</filename> exists in
212 the data directory, the contents of the file will be passed as
213 options to the <application>postmaster</application>, unless
214 overridden by the <option>-o</option> option.
221 <refsect1 id="R1-APP-PGCTL-2">
222 <title>Examples</title>
224 <refsect2 id="R2-APP-PGCTL-3">
225 <title>Starting the postmaster</title>
228 To start up <application>postmaster</application>:
230 <prompt>$</prompt> <userinput>pg_ctl start</userinput>
235 An example of starting the <application>postmaster</application>,
236 blocking until postmaster comes up is:
238 <prompt>$</prompt> <userinput>pg_ctl -w start</userinput>
243 For a <application>postmaster</application> using port 5433, and
244 running without <function>fsync</function>, use:
246 <prompt>$</prompt> <userinput>pg_ctl -o "-F -p 5433" start</userinput>
251 <refsect2 id="R2-APP-PGCTL-4">
252 <title>Stopping the postmaster</title>
255 <prompt>$</prompt> <userinput>pg_ctl stop</userinput>
257 stops postmaster. Using the <option>-m</option> switch allows one
258 to control <emphasis>how</emphasis> the backend shuts down.
262 <refsect2 id="R2-APP-PGCTL-5">
263 <title>Restarting the postmaster</title>
266 This is almost equivalent to stopping the
267 <application>postmaster</application> then starting it again
268 except that pg_ctl saves and reuses the command line options that
269 were passed to the previously running instance. To restart
270 <application>postmaster</application> in the simplest form:
272 <prompt>$</prompt> <userinput>pg_ctl restart</userinput>
277 To restart <application>postmaster</application>,
278 waiting for it to shut down and to come up:
280 <prompt>$</prompt> <userinput>pg_ctl -w restart</userinput>
285 To restart using port 5433 and disabling fsync after restarting:
287 <prompt>$</prompt> <userinput>pg_ctl -o "-F -p 5433" restart</userinput>
292 <refsect2 id="R2-APP-PGCTL-6">
293 <title>Showing postmaster status</title>
296 Here is a sample status output from
297 <application>pg_ctl</application>:
299 <prompt>$</prompt> <userinput>pg_ctl status</userinput>
301 pg_ctl: postmaster is running (pid: 13718)
303 /usr/local/pgsql/bin/postmaster '-D' '/usr/local/pgsql/data' '-p' '5433' '-B' '128'
306 This is the command line that would be invoked in restart mode.
315 Waiting for complete start is not a well-defined operation and may
316 fail if access control is set up in way that a local client cannot
317 connect without manual interaction. It should be avoided.
322 <title>See Also</title>
325 <xref linkend="app-postmaster">, <citetitle>PostgreSQL Administrator's Guide</citetitle>
331 <!-- Keep this comment at the end of the file
336 sgml-minimize-attributes:nil
337 sgml-always-quote-attributes:t
340 sgml-parent-document:nil
341 sgml-default-dtd-file:"../reference.ced"
342 sgml-exposed-tags:nil
343 sgml-local-catalogs:("/usr/lib/sgml/catalog")
344 sgml-local-ecat-files:nil