mirror of
https://git.postgresql.org/git/postgresql.git
synced 2024-09-08 13:39:21 +02:00
including: - replacing all the appropriate usages of <citetitle>PostgreSQL ...</citetitle> with &cite-user;, &cite-admin;, and so on - fix an omission in the EXECUTE documentation - add some more text to the EXPLAIN documentation - improve the PL/PgSQL RETURN NEXT documentation (more work to do here) - minor markup fixes Neil Conway
393 lines
11 KiB
Plaintext
393 lines
11 KiB
Plaintext
<!--
|
|
$Header: /cvsroot/pgsql/doc/src/sgml/ref/pg_ctl-ref.sgml,v 1.18 2003/01/19 00:13:30 momjian Exp $
|
|
PostgreSQL documentation
|
|
-->
|
|
|
|
<refentry id="app-pg-ctl">
|
|
<refmeta>
|
|
<refentrytitle id="app-pg-ctl-title"><application>pg_ctl</application></refentrytitle>
|
|
<manvolnum>1</manvolnum>
|
|
<refmiscinfo>Application</refmiscinfo>
|
|
</refmeta>
|
|
|
|
<refnamediv>
|
|
<refname>pg_ctl</refname>
|
|
<refpurpose>start, stop, or restart a <productname>PostgreSQL</productname> server</refpurpose>
|
|
</refnamediv>
|
|
|
|
<refsynopsisdiv>
|
|
<cmdsynopsis>
|
|
<command>pg_ctl</command>
|
|
<arg choice="plain">start</arg>
|
|
<arg>-w</arg>
|
|
<arg>-s</arg>
|
|
<arg>-D <replaceable>datadir</replaceable></arg>
|
|
<arg>-l <replaceable>filename</replaceable></arg>
|
|
<arg>-o <replaceable>options</replaceable></arg>
|
|
<arg>-p <replaceable>path</replaceable></arg>
|
|
<sbr>
|
|
<command>pg_ctl</command>
|
|
<arg choice="plain">stop</arg>
|
|
<arg>-W</arg>
|
|
<arg>-s</arg>
|
|
<arg>-D <replaceable>datadir</replaceable></arg>
|
|
<arg>-m
|
|
<group choice="plain">
|
|
<arg>s[mart]</arg>
|
|
<arg>f[ast]</arg>
|
|
<arg>i[mmediate]</arg>
|
|
</group>
|
|
</arg>
|
|
<sbr>
|
|
<command>pg_ctl</command>
|
|
<arg choice="plain">restart</arg>
|
|
<arg>-w</arg>
|
|
<arg>-s</arg>
|
|
<arg>-D <replaceable>datadir</replaceable></arg>
|
|
<arg>-m
|
|
<group choice="plain">
|
|
<arg>s[mart]</arg>
|
|
<arg>f[ast]</arg>
|
|
<arg>i[mmediate]</arg>
|
|
</group>
|
|
</arg>
|
|
<arg>-o <replaceable>options</replaceable></arg>
|
|
<sbr>
|
|
<command>pg_ctl</command>
|
|
<arg choice="plain">reload</arg>
|
|
<arg>-s</arg>
|
|
<arg>-D <replaceable>datadir</replaceable></arg>
|
|
<sbr>
|
|
<command>pg_ctl</command>
|
|
<arg choice="plain">status</arg>
|
|
<arg>-D <replaceable>datadir</replaceable></arg>
|
|
</cmdsynopsis>
|
|
</refsynopsisdiv>
|
|
|
|
|
|
<refsect1 id="app-pg-ctl-description">
|
|
<title>Description</title>
|
|
<para>
|
|
<application>pg_ctl</application> is a utility for starting,
|
|
stopping, or restarting <xref linkend="app-postmaster">, the
|
|
<productname>PostgreSQL</productname> backend server, or displaying
|
|
the status of a running postmaster. Although the postmaster can be
|
|
started manually, <application>pg_ctl</application> encapsulates
|
|
tasks such as redirecting log output, properly detaching from the
|
|
terminal and process group, and it provides convenient options for
|
|
controlled shutdown.
|
|
</para>
|
|
|
|
<para>
|
|
In <option>start</option> mode, a new postmaster is launched. The
|
|
server is started in the background, the standard input attached to
|
|
<filename>/dev/null</filename>. The standard output and standard
|
|
error are either appended to a log file, if the <option>-l</option>
|
|
option is used, or are redirected to
|
|
<application>pg_ctl</application>'s standard output (not standard
|
|
error). If no log file is chosen, the standard output of
|
|
<application>pg_ctl</application> should be redirected to a file or
|
|
piped to another process, for example a log rotating program,
|
|
otherwise the postmaster will write its output the the controlling
|
|
terminal (from the background) and will not leave the shell's
|
|
process group.
|
|
</para>
|
|
|
|
<para>
|
|
In <option>stop</option> mode, the postmaster that is running in
|
|
the specified data directory is shut down. Three different
|
|
shutdown methods can be selected with the <option>-m</option>
|
|
option: <quote>Smart</quote> mode waits for all the clients to
|
|
disconnect. This is the default. <quote>Fast</quote> mode does
|
|
not wait for clients to disconnect. All active transactions are
|
|
rolled back and clients are forcibly disconnected, then the
|
|
database is shut down. <quote>Immediate</quote> mode will abort
|
|
all server processes without clean shutdown. This will lead to a recovery
|
|
run on restart.
|
|
</para>
|
|
|
|
<para>
|
|
<option>restart</option> mode effectively executes a stop followed
|
|
by a start. This allows the changing of postmaster command line
|
|
options.
|
|
</para>
|
|
|
|
<para>
|
|
<option>reload</option> mode simply sends the postmaster a <systemitem>SIGHUP</> signal,
|
|
causing it to reread its configuration files
|
|
(<filename>postgresql.conf</filename>, <filename>pg_hba.conf</filename>,
|
|
etc.). This allows changing of configuration-file options that do not
|
|
require a complete restart to take effect.
|
|
</para>
|
|
|
|
<para>
|
|
<option>status</option> mode checks whether a postmaster is running
|
|
and if so displays the <acronym>PID</acronym> and the command line
|
|
options that were used to invoke it.
|
|
</para>
|
|
</refsect1>
|
|
|
|
<refsect1 id="app-pg-ctl-options">
|
|
<title>Options</title>
|
|
|
|
<para>
|
|
|
|
<variablelist>
|
|
<varlistentry>
|
|
<term>-D <replaceable class="parameter">datadir</replaceable></term>
|
|
<listitem>
|
|
<para>
|
|
Specifies the file system location of the database files. If
|
|
this is omitted, the environment variable
|
|
<envar>PGDATA</envar> is used.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term>-l <replaceable class="parameter">filename</replaceable></term>
|
|
<listitem>
|
|
<para>
|
|
Append the server log output to
|
|
<replaceable>filename</replaceable>. If the file does not
|
|
exist, it is created. The <systemitem>umask</> is set to 077, so access to
|
|
the log file from other users is disallowed by default.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term>-m <replaceable class="parameter">mode</replaceable></term>
|
|
<listitem>
|
|
<para>
|
|
Specifies the shutdown mode. <replaceable>mode</replaceable>
|
|
may be <literal>smart</literal>, <literal>fast</literal>, or
|
|
<literal>immediate</literal>, or the first letter of one of
|
|
these three.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term>-o <replaceable class="parameter">options</replaceable></term>
|
|
<listitem>
|
|
<para>
|
|
Specifies options to be passed directly to
|
|
<application>postmaster</application>.
|
|
</para>
|
|
<para>
|
|
The parameters are usually surrounded by single or double
|
|
quotes to ensure that they are passed through as a group.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term>-p <replaceable class="parameter">path</replaceable></term>
|
|
<listitem>
|
|
<para>
|
|
Specifies the location of the <filename>postmaster</filename>
|
|
executable. By default the postmaster is taken from the same
|
|
directory as <command>pg_ctl</>, or failing that, the hard-wired
|
|
installation directory. It is not necessary to use this
|
|
option unless you are doing something unusual and get errors
|
|
that the postmaster was not found.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term>-s</term>
|
|
<listitem>
|
|
<para>
|
|
Only print errors, no informational messages.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term>-w</term>
|
|
<listitem>
|
|
<para>
|
|
Wait for the start or shutdown to complete. Times out after
|
|
60 seconds. This is the default for shutdowns.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term>-W</term>
|
|
<listitem>
|
|
<para>
|
|
Do not wait for start or shutdown to complete. This is the
|
|
default for starts and restarts.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
</variablelist>
|
|
</para>
|
|
</refsect1>
|
|
|
|
|
|
<refsect1>
|
|
<title>Environment</title>
|
|
|
|
<variablelist>
|
|
<varlistentry>
|
|
<term><envar>PGDATA</envar></term>
|
|
|
|
<listitem>
|
|
<para>
|
|
Default data direction location
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
</variablelist>
|
|
|
|
<para>
|
|
For others, see <xref linkend="app-postmaster">.
|
|
</para>
|
|
</refsect1>
|
|
|
|
|
|
<refsect1>
|
|
<title>Files</title>
|
|
|
|
<para>
|
|
If the file <filename>postmaster.opts.default</filename> exists in
|
|
the data directory, the contents of the file will be passed as
|
|
options to the <application>postmaster</application>, unless
|
|
overridden by the <option>-o</option> option.
|
|
</para>
|
|
</refsect1>
|
|
|
|
|
|
<refsect1>
|
|
<title>Notes</title>
|
|
|
|
<para>
|
|
Waiting for complete start is not a well-defined operation and may
|
|
fail if access control is set up so that a local client cannot
|
|
connect without manual interaction. It should be avoided.
|
|
</para>
|
|
</refsect1>
|
|
|
|
|
|
<refsect1 id="R1-APP-PGCTL-2">
|
|
<title>Examples</title>
|
|
|
|
<refsect2 id="R2-APP-PGCTL-3">
|
|
<title>Starting the postmaster</title>
|
|
|
|
<para>
|
|
To start up a <application>postmaster</application>:
|
|
<screen>
|
|
<prompt>$</prompt> <userinput>pg_ctl start</userinput>
|
|
</screen>
|
|
</para>
|
|
|
|
<para>
|
|
An example of starting the <application>postmaster</application>,
|
|
blocking until the postmaster comes up is:
|
|
<screen>
|
|
<prompt>$</prompt> <userinput>pg_ctl -w start</userinput>
|
|
</screen>
|
|
</para>
|
|
|
|
<para>
|
|
For a <application>postmaster</application> using port 5433, and
|
|
running without <function>fsync</function>, use:
|
|
<screen>
|
|
<prompt>$</prompt> <userinput>pg_ctl -o "-F -p 5433" start</userinput>
|
|
</screen>
|
|
</para>
|
|
</refsect2>
|
|
|
|
<refsect2 id="R2-APP-PGCTL-4">
|
|
<title>Stopping the postmaster</title>
|
|
<para>
|
|
<screen>
|
|
<prompt>$</prompt> <userinput>pg_ctl stop</userinput>
|
|
</screen>
|
|
stops the postmaster. Using the <option>-m</option> switch allows one
|
|
to control <emphasis>how</emphasis> the backend shuts down.
|
|
</para>
|
|
</refsect2>
|
|
|
|
<refsect2 id="R2-APP-PGCTL-5">
|
|
<title>Restarting the postmaster</title>
|
|
|
|
<para>
|
|
This is almost equivalent to stopping the
|
|
<application>postmaster</application> and starting it again
|
|
except that <command>pg_ctl</command> saves and reuses the command line options that
|
|
were passed to the previously running instance. To restart
|
|
the <application>postmaster</application> in the simplest form:
|
|
<screen>
|
|
<prompt>$</prompt> <userinput>pg_ctl restart</userinput>
|
|
</screen>
|
|
</para>
|
|
|
|
<para>
|
|
To restart <application>postmaster</application>,
|
|
waiting for it to shut down and to come up:
|
|
<screen>
|
|
<prompt>$</prompt> <userinput>pg_ctl -w restart</userinput>
|
|
</screen>
|
|
</para>
|
|
|
|
<para>
|
|
To restart using port 5433 and disabling <function>fsync</> after restarting:
|
|
<screen>
|
|
<prompt>$</prompt> <userinput>pg_ctl -o "-F -p 5433" restart</userinput>
|
|
</screen>
|
|
</para>
|
|
</refsect2>
|
|
|
|
<refsect2 id="R2-APP-PGCTL-6">
|
|
<title>Showing postmaster status</title>
|
|
|
|
<para>
|
|
Here is a sample status output from
|
|
<application>pg_ctl</application>:
|
|
<screen>
|
|
<prompt>$</prompt> <userinput>pg_ctl status</userinput>
|
|
<computeroutput>
|
|
pg_ctl: postmaster is running (pid: 13718)
|
|
Command line was:
|
|
/usr/local/pgsql/bin/postmaster '-D' '/usr/local/pgsql/data' '-p' '5433' '-B' '128'
|
|
</computeroutput>
|
|
</screen>
|
|
This is the command line that would be invoked in restart mode.
|
|
</para>
|
|
</refsect2>
|
|
</refsect1>
|
|
|
|
|
|
<refsect1>
|
|
<title>See Also</title>
|
|
|
|
<para>
|
|
<xref linkend="app-postmaster">, &cite-admin;
|
|
</para>
|
|
</refsect1>
|
|
|
|
</refentry>
|
|
|
|
<!-- Keep this comment at the end of the file
|
|
Local variables:
|
|
mode:sgml
|
|
sgml-omittag:nil
|
|
sgml-shorttag:t
|
|
sgml-minimize-attributes:nil
|
|
sgml-always-quote-attributes:t
|
|
sgml-indent-step:1
|
|
sgml-indent-data:t
|
|
sgml-parent-document:nil
|
|
sgml-default-dtd-file:"../reference.ced"
|
|
sgml-exposed-tags:nil
|
|
sgml-local-catalogs:("/usr/lib/sgml/catalog")
|
|
sgml-local-ecat-files:nil
|
|
End:
|
|
-->
|