2 doc/src/sgml/ref/pg_ctl-ref.sgml
3 PostgreSQL documentation
6 <refentry id="app-pg-ctl">
8 <refentrytitle><application>pg_ctl</application></refentrytitle>
9 <manvolnum>1</manvolnum>
10 <refmiscinfo>Application</refmiscinfo>
14 <refname>pg_ctl</refname>
15 <refpurpose>initialize, start, stop, or restart a <productname>PostgreSQL</productname> server</refpurpose>
18 <indexterm zone="app-pg-ctl">
19 <primary>pg_ctl</primary>
24 <command>pg_ctl</command>
25 <arg choice="plain">init[db]</arg>
27 <arg>-D <replaceable>datadir</replaceable></arg>
28 <arg>-o <replaceable>initdb-options</replaceable></arg>
32 <command>pg_ctl</command>
33 <arg choice="plain">start</arg>
35 <arg>-t <replaceable>seconds</replaceable></arg>
37 <arg>-D <replaceable>datadir</replaceable></arg>
38 <arg>-l <replaceable>filename</replaceable></arg>
39 <arg>-o <replaceable>options</replaceable></arg>
40 <arg>-p <replaceable>path</replaceable></arg>
45 <command>pg_ctl</command>
46 <arg choice="plain">stop</arg>
48 <arg>-t <replaceable>seconds</replaceable></arg>
50 <arg>-D <replaceable>datadir</replaceable></arg>
52 <group choice="plain">
55 <arg>i[mmediate]</arg>
61 <command>pg_ctl</command>
62 <arg choice="plain">restart</arg>
64 <arg>-t <replaceable>seconds</replaceable></arg>
66 <arg>-D <replaceable>datadir</replaceable></arg>
69 <group choice="plain">
72 <arg>i[mmediate]</arg>
75 <arg>-o <replaceable>options</replaceable></arg>
79 <command>pg_ctl</command>
80 <arg choice="plain">reload</arg>
82 <arg>-D <replaceable>datadir</replaceable></arg>
86 <command>pg_ctl</command>
87 <arg choice="plain">status</arg>
88 <arg>-D <replaceable>datadir</replaceable></arg>
92 <command>pg_ctl</command>
93 <arg choice="plain">kill</arg>
94 <arg><replaceable>signal_name</replaceable></arg>
95 <arg><replaceable>process_id</replaceable></arg>
99 <command>pg_ctl</command>
100 <arg choice="plain">register</arg>
101 <arg>-N <replaceable>servicename</replaceable></arg>
102 <arg>-U <replaceable>username</replaceable></arg>
103 <arg>-P <replaceable>password</replaceable></arg>
104 <arg>-D <replaceable>datadir</replaceable></arg>
106 <group choice="plain">
112 <arg>-t <replaceable>seconds</replaceable></arg>
113 <arg>-o <replaceable>options</replaceable></arg>
117 <command>pg_ctl</command>
118 <arg choice="plain">unregister</arg>
119 <arg>-N <replaceable>servicename</replaceable></arg>
124 <refsect1 id="app-pg-ctl-description">
125 <title>Description</title>
127 <application>pg_ctl</application> is a utility for initializing a
128 <productname>PostgreSQL</productname> database cluster, starting,
129 stopping, or restarting the <productname>PostgreSQL</productname>
130 backend server (<xref linkend="app-postgres">), or displaying the
131 status of a running server. Although the server can be started
132 manually, <application>pg_ctl</application> encapsulates tasks such
133 as redirecting log output and properly detaching from the terminal
134 and process group. It also provides convenient options for
139 The <option>init</option> or <option>initdb</option> mode creates a new
140 <productname>PostgreSQL</productname> database cluster. A database
141 cluster is a collection of databases that are managed by a single
142 server instance. This mode invokes the <command>initdb</command>
143 command. See <xref linkend="app-initdb"> for details.
147 In <option>start</option> mode, a new server is launched. The
148 server is started in the background, and its standard input is attached
149 to <filename>/dev/null</filename> (or <literal>nul</> on Windows).
150 On Unix-like systems, by default, the server's standard output and
151 standard error are sent to <application>pg_ctl</application>'s
152 standard output (not standard error). The standard output of
153 <application>pg_ctl</application> should then be redirected to a
154 file or piped to another process such as a log rotating program
155 like <application>rotatelogs</>; otherwise <command>postgres</command>
156 will write its output to the controlling terminal (from the
157 background) and will not leave the shell's process group. On
158 Windows, by default the server's standard output and standard error
159 are sent to the terminal. These default behaviors can be changed
160 by using <option>-l</option> to append the server's output to a log file.
161 Use of either <option>-l</option> or output redirection is recommended.
165 In <option>stop</option> mode, the server that is running in
166 the specified data directory is shut down. Three different
167 shutdown methods can be selected with the <option>-m</option>
168 option. <quote>Smart</quote> mode (the default) waits for all active
169 clients to disconnect and any online backup to finish.
170 If the server is in hot standby, recovery and streaming replication
171 will be terminated once all clients have disconnected.
172 <quote>Fast</quote> mode does not wait for clients to disconnect and
173 will terminate an online backup in progress. All active transactions are
174 rolled back and clients are forcibly disconnected, then the
175 server is shut down. <quote>Immediate</quote> mode will abort
176 all server processes immediately, without a clean shutdown.
177 This will lead to a crash-recovery run on the next restart.
181 <option>restart</option> mode effectively executes a stop followed
182 by a start. This allows changing the <command>postgres</command>
183 command-line options.
187 <option>reload</option> mode simply sends the
188 <command>postgres</command> process a <systemitem>SIGHUP</>
189 signal, causing it to reread its configuration files
190 (<filename>postgresql.conf</filename>,
191 <filename>pg_hba.conf</filename>, etc.). This allows changing of
192 configuration-file options that do not require a complete restart
197 <option>status</option> mode checks whether a server is running in
198 the specified data directory. If it is, the <acronym>PID</acronym>
199 and the command line options that were used to invoke it are
204 <option>kill</option> mode allows you to send a signal to a specified
205 process. This is particularly valuable for <productname>Microsoft Windows</>
206 which does not have a <application>kill</> command. Use
207 <literal>--help</> to see a list of supported signal names.
211 <option>register</option> mode allows you to register a system service
212 on <productname>Microsoft Windows</>. The <option>-S</option> option
213 allows selection of service start type, either <quote>auto</quote> (start
214 service automatically on system startup) or <quote>demand</quote> (start
219 <option>unregister</option> mode allows you to unregister a system service
220 on <productname>Microsoft Windows</>. This undoes the effects of the
221 <option>register</option> command.
225 <refsect1 id="app-pg-ctl-options">
226 <title>Options</title>
231 <term><option>-c</option></term>
234 Attempt to allow server crashes to produce core files, on platforms
235 where this is possible, by lifting any soft resource limit placed on
237 This is useful in debugging or diagnosing problems by allowing a
238 stack trace to be obtained from a failed server process.
244 <term><option>-D <replaceable class="parameter">datadir</replaceable></option></term>
247 Specifies the file system location of the database files. If
248 this is omitted, the environment variable
249 <envar>PGDATA</envar> is used.
255 <term><option>-l <replaceable class="parameter">filename</replaceable></option></term>
258 Append the server log output to
259 <replaceable>filename</replaceable>. If the file does not
260 exist, it is created. The <systemitem>umask</> is set to 077,
261 so access to the log file is disallowed to other users by default.
267 <term><option>-m <replaceable class="parameter">mode</replaceable></option></term>
270 Specifies the shutdown mode. <replaceable>mode</replaceable>
271 can be <literal>smart</literal>, <literal>fast</literal>, or
272 <literal>immediate</literal>, or the first letter of one of
273 these three. If this is omitted, <literal>smart</literal> is used.
279 <term><option>-o <replaceable class="parameter">options</replaceable></option></term>
282 Specifies options to be passed directly to the
283 <command>postgres</command> command.
286 The options should usually be surrounded by single or double
287 quotes to ensure that they are passed through as a group.
293 <term><option>-o <replaceable class="parameter">initdb-options</replaceable></option></term>
296 Specifies options to be passed directly to the
297 <command>initdb</command> command.
300 The options should usually be surrounded by single or double
301 quotes to ensure that they are passed through as a group.
307 <term><option>-p <replaceable class="parameter">path</replaceable></option></term>
310 Specifies the location of the <filename>postgres</filename>
311 executable. By default the <filename>postgres</filename> executable is taken from the same
312 directory as <command>pg_ctl</command>, or failing that, the hard-wired
313 installation directory. It is not necessary to use this
314 option unless you are doing something unusual and get errors
315 that the <filename>postgres</filename> executable was not found.
319 In <literal>init</literal> mode, this option analogously
320 specifies the location of the <filename>initdb</filename>
327 <term><option>-s</option></term>
330 Print only errors, no informational messages.
336 <term><option>-t</option></term>
339 The maximum number of seconds to wait when waiting for startup or
340 shutdown to complete. The default is 60 seconds.
346 <term><option>-w</option></term>
349 Wait for the startup or shutdown to complete.
350 Waiting is the default option for shutdowns, but not startups.
351 When waiting for shutdown, <command>pg_ctl</command> waits for
352 the server to remove its <acronym>PID</acronym> file.
353 When waiting for startup, <command>pg_ctl</command> repeatedly
354 attempts to connect to the server via <application>psql</>, and
355 reports success when this is successful.
356 <command>pg_ctl</command> will attempt to use the proper port for
357 <application>psql</>. If the environment variable
358 <envar>PGPORT</envar> exists, that is used. Otherwise,
359 <command>pg_ctl</command> will see if a port has been set in the
360 <filename>postgresql.conf</filename> file. If not, it will use the
361 default port that <productname>PostgreSQL</productname> was compiled
362 with (5432 by default).
363 When waiting, <command>pg_ctl</command> will
364 return an exit code based on the success of the startup
371 <term><option>-W</option></term>
374 Do not wait for startup or shutdown to complete. This is the
375 default for start and restart modes.
381 <refsect2 id="app-pg-ctl-windows-options">
382 <title>Options for Windows</title>
386 <term><option>-N <replaceable class="parameter">servicename</replaceable></option></term>
389 Name of the system service to register. The name will be used
390 as both the service name and the display name.
396 <term><option>-U <replaceable class="parameter">username</replaceable></option></term>
399 User name for the user to start the service. For domain users, use the
400 format <literal>DOMAIN\username</literal>.
406 <term><option>-P <replaceable class="parameter">password</replaceable></option></term>
409 Password for the user to start the service.
415 <term><option>-S <replaceable class="parameter">start-type</replaceable></option></term>
418 Start type of the system service to register. start-type can
419 be <literal>auto</literal>, or <literal>demand</literal>, or
420 the first letter of one of these two. If this is omitted,
421 <literal>auto</literal> is used.
432 <title>Environment</title>
436 <term><envar>PGDATA</envar></term>
440 Default data directory location.
446 <term><envar>PGHOST</envar></term>
450 Default host name or Unix-domain socket location for <xref
451 linkend="app-psql"> (used when waiting for startup).
457 <term><envar>PGPORT</envar></term>
461 Default port number for <xref linkend="app-psql">
462 (used when waiting for startup).
470 <command>pg_ctl</command>, like most other <productname>PostgreSQL</>
472 also uses the environment variables supported by <application>libpq</>
473 (see <xref linkend="libpq-envars">).
474 For additional server variables, see <xref linkend="app-postgres">.
484 <term><filename>postmaster.pid</filename></term>
488 The existence of this file in the data directory is used to help
489 <application>pg_ctl</application> determine if the server is
490 currently running or not.
496 <term><filename>postmaster.opts</filename></term>
499 <para>If this file exists in the data directory,
500 <application>pg_ctl</application> (in <option>restart</option> mode)
501 will pass the contents of the file as options to
502 <application>postgres</application>, unless overridden
503 by the <option>-o</option> option. The contents of this file
504 are also displayed in <option>status</option> mode.
510 <term><filename>postgresql.conf</filename></term>
514 This file, located in the data directory, is parsed to find the
515 proper port to use with <application>psql</application>
516 when waiting for startup.
529 Waiting for complete startup is not a well-defined operation and might
530 fail if access control is set up so that a local client cannot
531 connect without manual interaction (e.g., password authentication). For
532 additional connection variables, see <xref linkend="libpq-envars">,
533 and for passwords, also see <xref linkend="libpq-pgpass">.
538 <refsect1 id="R1-APP-PGCTL-2">
539 <title>Examples</title>
541 <refsect2 id="R2-APP-PGCTL-3">
542 <title>Starting the Server</title>
545 To start up a server:
547 <prompt>$</prompt> <userinput>pg_ctl start</userinput>
552 An example of starting the server, blocking until the server has
555 <prompt>$</prompt> <userinput>pg_ctl -w start</userinput>
560 For a server using port 5433, and
561 running without <function>fsync</function>, use:
563 <prompt>$</prompt> <userinput>pg_ctl -o "-F -p 5433" start</userinput>
568 <refsect2 id="R2-APP-PGCTL-4">
569 <title>Stopping the Server</title>
572 <prompt>$</prompt> <userinput>pg_ctl stop</userinput>
574 stops the server. Using the <option>-m</option> switch allows one
575 to control <emphasis>how</emphasis> the backend shuts down.
579 <refsect2 id="R2-APP-PGCTL-5">
580 <title>Restarting the Server</title>
583 Restarting the server is almost equivalent to stopping the
584 server and starting it again
585 except that <command>pg_ctl</command> saves and reuses the command line options that
586 were passed to the previously running instance. To restart
587 the server in the simplest form, use:
589 <prompt>$</prompt> <userinput>pg_ctl restart</userinput>
594 To restart the server,
595 waiting for it to shut down and come up again:
597 <prompt>$</prompt> <userinput>pg_ctl -w restart</userinput>
602 To restart using port 5433 and disabling <function>fsync</> after restarting:
604 <prompt>$</prompt> <userinput>pg_ctl -o "-F -p 5433" restart</userinput>
609 <refsect2 id="R2-APP-PGCTL-6">
610 <title>Showing the Server Status</title>
613 Here is a sample status output from
614 <application>pg_ctl</application>:
616 <prompt>$</prompt> <userinput>pg_ctl status</userinput>
618 pg_ctl: server is running (PID: 13718)
619 /usr/local/pgsql/bin/postgres "-D" "/usr/local/pgsql/data" "-p" "5433" "-B" "128"
622 This is the command line that would be invoked in restart mode.
629 <title>See Also</title>
631 <simplelist type="inline">
632 <member><xref linkend="app-initdb"></member>
633 <member><xref linkend="app-postgres"></member>