mirror of
https://github.com/postgres/postgres.git
synced 2025-05-05 09:19:17 +03:00
0de92fd13c
Explicitly document that the -o options of pg_ctl init mode are meant for initdb, not postgres (Euler Taveira de Oliveira). Assorted other copy-editing (Tom).
639 lines
20 KiB
Plaintext
639 lines
20 KiB
Plaintext
<!--
|
|
doc/src/sgml/ref/pg_ctl-ref.sgml
|
|
PostgreSQL documentation
|
|
-->
|
|
|
|
<refentry id="app-pg-ctl">
|
|
<refmeta>
|
|
<refentrytitle><application>pg_ctl</application></refentrytitle>
|
|
<manvolnum>1</manvolnum>
|
|
<refmiscinfo>Application</refmiscinfo>
|
|
</refmeta>
|
|
|
|
<refnamediv>
|
|
<refname>pg_ctl</refname>
|
|
<refpurpose>initialize, start, stop, or restart a <productname>PostgreSQL</productname> server</refpurpose>
|
|
</refnamediv>
|
|
|
|
<indexterm zone="app-pg-ctl">
|
|
<primary>pg_ctl</primary>
|
|
</indexterm>
|
|
|
|
<refsynopsisdiv>
|
|
<cmdsynopsis>
|
|
<command>pg_ctl</command>
|
|
<arg choice="plain">init[db]</arg>
|
|
<arg>-s</arg>
|
|
<arg>-D <replaceable>datadir</replaceable></arg>
|
|
<arg>-o <replaceable>initdb-options</replaceable></arg>
|
|
</cmdsynopsis>
|
|
|
|
<cmdsynopsis>
|
|
<command>pg_ctl</command>
|
|
<arg choice="plain">start</arg>
|
|
<arg>-w</arg>
|
|
<arg>-t <replaceable>seconds</replaceable></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>
|
|
<arg>-c</arg>
|
|
</cmdsynopsis>
|
|
|
|
<cmdsynopsis>
|
|
<command>pg_ctl</command>
|
|
<arg choice="plain">stop</arg>
|
|
<arg>-W</arg>
|
|
<arg>-t <replaceable>seconds</replaceable></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>
|
|
</cmdsynopsis>
|
|
|
|
<cmdsynopsis>
|
|
<command>pg_ctl</command>
|
|
<arg choice="plain">restart</arg>
|
|
<arg>-w</arg>
|
|
<arg>-t <replaceable>seconds</replaceable></arg>
|
|
<arg>-s</arg>
|
|
<arg>-D <replaceable>datadir</replaceable></arg>
|
|
<arg>-c</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>
|
|
</cmdsynopsis>
|
|
|
|
<cmdsynopsis>
|
|
<command>pg_ctl</command>
|
|
<arg choice="plain">reload</arg>
|
|
<arg>-s</arg>
|
|
<arg>-D <replaceable>datadir</replaceable></arg>
|
|
</cmdsynopsis>
|
|
|
|
<cmdsynopsis>
|
|
<command>pg_ctl</command>
|
|
<arg choice="plain">status</arg>
|
|
<arg>-D <replaceable>datadir</replaceable></arg>
|
|
</cmdsynopsis>
|
|
|
|
<cmdsynopsis>
|
|
<command>pg_ctl</command>
|
|
<arg choice="plain">kill</arg>
|
|
<arg><replaceable>signal_name</replaceable></arg>
|
|
<arg><replaceable>process_id</replaceable></arg>
|
|
</cmdsynopsis>
|
|
|
|
<cmdsynopsis>
|
|
<command>pg_ctl</command>
|
|
<arg choice="plain">register</arg>
|
|
<arg>-N <replaceable>servicename</replaceable></arg>
|
|
<arg>-U <replaceable>username</replaceable></arg>
|
|
<arg>-P <replaceable>password</replaceable></arg>
|
|
<arg>-D <replaceable>datadir</replaceable></arg>
|
|
<arg>-S
|
|
<group choice="plain">
|
|
<arg>a[uto]</arg>
|
|
<arg>d[emand]</arg>
|
|
</group>
|
|
</arg>
|
|
<arg>-w</arg>
|
|
<arg>-t <replaceable>seconds</replaceable></arg>
|
|
<arg>-o <replaceable>options</replaceable></arg>
|
|
</cmdsynopsis>
|
|
|
|
<cmdsynopsis>
|
|
<command>pg_ctl</command>
|
|
<arg choice="plain">unregister</arg>
|
|
<arg>-N <replaceable>servicename</replaceable></arg>
|
|
</cmdsynopsis>
|
|
</refsynopsisdiv>
|
|
|
|
|
|
<refsect1 id="app-pg-ctl-description">
|
|
<title>Description</title>
|
|
<para>
|
|
<application>pg_ctl</application> is a utility for initializing a
|
|
<productname>PostgreSQL</productname> database cluster, starting,
|
|
stopping, or restarting the <productname>PostgreSQL</productname>
|
|
backend server (<xref linkend="app-postgres">), or displaying the
|
|
status of a running server. Although the server can be started
|
|
manually, <application>pg_ctl</application> encapsulates tasks such
|
|
as redirecting log output and properly detaching from the terminal
|
|
and process group. It also provides convenient options for
|
|
controlled shutdown.
|
|
</para>
|
|
|
|
<para>
|
|
The <option>init</option> or <option>initdb</option> mode creates a new
|
|
<productname>PostgreSQL</productname> database cluster. A database
|
|
cluster is a collection of databases that are managed by a single
|
|
server instance. This mode invokes the <command>initdb</command>
|
|
command. See <xref linkend="app-initdb"> for details.
|
|
</para>
|
|
|
|
<para>
|
|
In <option>start</option> mode, a new server is launched. The
|
|
server is started in the background, and its standard input is attached
|
|
to <filename>/dev/null</filename> (or <literal>nul</> on Windows).
|
|
On Unix-like systems, by default, the server's standard output and
|
|
standard error are sent to <application>pg_ctl</application>'s
|
|
standard output (not standard error). The standard output of
|
|
<application>pg_ctl</application> should then be redirected to a
|
|
file or piped to another process such as a log rotating program
|
|
like <application>rotatelogs</>; otherwise <command>postgres</command>
|
|
will write its output to the controlling terminal (from the
|
|
background) and will not leave the shell's process group. On
|
|
Windows, by default the server's standard output and standard error
|
|
are sent to the terminal. These default behaviors can be changed
|
|
by using <option>-l</option> to append the server's output to a log file.
|
|
Use of either <option>-l</option> or output redirection is recommended.
|
|
</para>
|
|
|
|
<para>
|
|
In <option>stop</option> mode, the server 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 (the default) waits for all active
|
|
clients to disconnect and any online backup to finish.
|
|
If the server is in hot standby, recovery and streaming replication
|
|
will be terminated once all clients have disconnected.
|
|
<quote>Fast</quote> mode does not wait for clients to disconnect and
|
|
will terminate an online backup in progress. All active transactions are
|
|
rolled back and clients are forcibly disconnected, then the
|
|
server is shut down. <quote>Immediate</quote> mode will abort
|
|
all server processes immediately, without a clean shutdown.
|
|
This will lead to a crash-recovery run on the next restart.
|
|
</para>
|
|
|
|
<para>
|
|
<option>restart</option> mode effectively executes a stop followed
|
|
by a start. This allows changing the <command>postgres</command>
|
|
command-line options.
|
|
</para>
|
|
|
|
<para>
|
|
<option>reload</option> mode simply sends the
|
|
<command>postgres</command> process 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 server is running in
|
|
the specified data directory. If it is, the <acronym>PID</acronym>
|
|
and the command line options that were used to invoke it are
|
|
displayed.
|
|
</para>
|
|
|
|
<para>
|
|
<option>kill</option> mode allows you to send a signal to a specified
|
|
process. This is particularly valuable for <productname>Microsoft Windows</>
|
|
which does not have a <application>kill</> command. Use
|
|
<literal>--help</> to see a list of supported signal names.
|
|
</para>
|
|
|
|
<para>
|
|
<option>register</option> mode allows you to register a system service
|
|
on <productname>Microsoft Windows</>. The <option>-S</option> option
|
|
allows selection of service start type, either <quote>auto</quote> (start
|
|
service automatically on system startup) or <quote>demand</quote> (start
|
|
service on demand).
|
|
</para>
|
|
|
|
<para>
|
|
<option>unregister</option> mode allows you to unregister a system service
|
|
on <productname>Microsoft Windows</>. This undoes the effects of the
|
|
<option>register</option> command.
|
|
</para>
|
|
</refsect1>
|
|
|
|
<refsect1 id="app-pg-ctl-options">
|
|
<title>Options</title>
|
|
|
|
<variablelist>
|
|
|
|
<varlistentry>
|
|
<term><option>-c</option></term>
|
|
<listitem>
|
|
<para>
|
|
Attempt to allow server crashes to produce core files, on platforms
|
|
where this is possible, by lifting any soft resource limit placed on
|
|
core files.
|
|
This is useful in debugging or diagnosing problems by allowing a
|
|
stack trace to be obtained from a failed server process.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term><option>-D <replaceable class="parameter">datadir</replaceable></option></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><option>-l <replaceable class="parameter">filename</replaceable></option></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 is disallowed to other users by default.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term><option>-m <replaceable class="parameter">mode</replaceable></option></term>
|
|
<listitem>
|
|
<para>
|
|
Specifies the shutdown mode. <replaceable>mode</replaceable>
|
|
can be <literal>smart</literal>, <literal>fast</literal>, or
|
|
<literal>immediate</literal>, or the first letter of one of
|
|
these three. If this is omitted, <literal>smart</literal> is used.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term><option>-o <replaceable class="parameter">options</replaceable></option></term>
|
|
<listitem>
|
|
<para>
|
|
Specifies options to be passed directly to the
|
|
<command>postgres</command> command.
|
|
</para>
|
|
<para>
|
|
The options should usually be surrounded by single or double
|
|
quotes to ensure that they are passed through as a group.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term><option>-o <replaceable class="parameter">initdb-options</replaceable></option></term>
|
|
<listitem>
|
|
<para>
|
|
Specifies options to be passed directly to the
|
|
<command>initdb</command> command.
|
|
</para>
|
|
<para>
|
|
The options should usually be surrounded by single or double
|
|
quotes to ensure that they are passed through as a group.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term><option>-p <replaceable class="parameter">path</replaceable></option></term>
|
|
<listitem>
|
|
<para>
|
|
Specifies the location of the <filename>postgres</filename>
|
|
executable. By default the <filename>postgres</filename> executable is taken from the same
|
|
directory as <command>pg_ctl</command>, 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 <filename>postgres</filename> executable was not found.
|
|
</para>
|
|
|
|
<para>
|
|
In <literal>init</literal> mode, this option analogously
|
|
specifies the location of the <filename>initdb</filename>
|
|
executable.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term><option>-s</option></term>
|
|
<listitem>
|
|
<para>
|
|
Print only errors, no informational messages.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term><option>-t</option></term>
|
|
<listitem>
|
|
<para>
|
|
The maximum number of seconds to wait when waiting for startup or
|
|
shutdown to complete. The default is 60 seconds.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term><option>-w</option></term>
|
|
<listitem>
|
|
<para>
|
|
Wait for the startup or shutdown to complete.
|
|
Waiting is the default option for shutdowns, but not startups.
|
|
When waiting for shutdown, <command>pg_ctl</command> waits for
|
|
the server to remove its <acronym>PID</acronym> file.
|
|
When waiting for startup, <command>pg_ctl</command> repeatedly
|
|
attempts to connect to the server via <application>psql</>, and
|
|
reports success when this is successful.
|
|
<command>pg_ctl</command> will attempt to use the proper port for
|
|
<application>psql</>. If the environment variable
|
|
<envar>PGPORT</envar> exists, that is used. Otherwise,
|
|
<command>pg_ctl</command> will see if a port has been set in the
|
|
<filename>postgresql.conf</filename> file. If not, it will use the
|
|
default port that <productname>PostgreSQL</productname> was compiled
|
|
with (5432 by default).
|
|
When waiting, <command>pg_ctl</command> will
|
|
return an exit code based on the success of the startup
|
|
or shutdown.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term><option>-W</option></term>
|
|
<listitem>
|
|
<para>
|
|
Do not wait for startup or shutdown to complete. This is the
|
|
default for start and restart modes.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
</variablelist>
|
|
|
|
<refsect2 id="app-pg-ctl-windows-options">
|
|
<title>Options for Windows</title>
|
|
|
|
<variablelist>
|
|
<varlistentry>
|
|
<term><option>-N <replaceable class="parameter">servicename</replaceable></option></term>
|
|
<listitem>
|
|
<para>
|
|
Name of the system service to register. The name will be used
|
|
as both the service name and the display name.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term><option>-U <replaceable class="parameter">username</replaceable></option></term>
|
|
<listitem>
|
|
<para>
|
|
User name for the user to start the service. For domain users, use the
|
|
format <literal>DOMAIN\username</literal>.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term><option>-P <replaceable class="parameter">password</replaceable></option></term>
|
|
<listitem>
|
|
<para>
|
|
Password for the user to start the service.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term><option>-S <replaceable class="parameter">start-type</replaceable></option></term>
|
|
<listitem>
|
|
<para>
|
|
Start type of the system service to register. start-type can
|
|
be <literal>auto</literal>, or <literal>demand</literal>, or
|
|
the first letter of one of these two. If this is omitted,
|
|
<literal>auto</literal> is used.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
</variablelist>
|
|
</refsect2>
|
|
|
|
</refsect1>
|
|
|
|
|
|
<refsect1>
|
|
<title>Environment</title>
|
|
|
|
<variablelist>
|
|
<varlistentry>
|
|
<term><envar>PGDATA</envar></term>
|
|
|
|
<listitem>
|
|
<para>
|
|
Default data directory location.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term><envar>PGHOST</envar></term>
|
|
|
|
<listitem>
|
|
<para>
|
|
Default host name or Unix-domain socket location for <xref
|
|
linkend="app-psql"> (used when waiting for startup).
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term><envar>PGPORT</envar></term>
|
|
|
|
<listitem>
|
|
<para>
|
|
Default port number for <xref linkend="app-psql">
|
|
(used when waiting for startup).
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
</variablelist>
|
|
|
|
<para>
|
|
<command>pg_ctl</command>, like most other <productname>PostgreSQL</>
|
|
utilities,
|
|
also uses the environment variables supported by <application>libpq</>
|
|
(see <xref linkend="libpq-envars">).
|
|
For additional server variables, see <xref linkend="app-postgres">.
|
|
</para>
|
|
</refsect1>
|
|
|
|
|
|
<refsect1>
|
|
<title>Files</title>
|
|
|
|
<variablelist>
|
|
<varlistentry>
|
|
<term><filename>postmaster.pid</filename></term>
|
|
|
|
<listitem>
|
|
<para>
|
|
The existence of this file in the data directory is used to help
|
|
<application>pg_ctl</application> determine if the server is
|
|
currently running or not.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term><filename>postmaster.opts</filename></term>
|
|
|
|
<listitem>
|
|
<para>If this file exists in the data directory,
|
|
<application>pg_ctl</application> (in <option>restart</option> mode)
|
|
will pass the contents of the file as options to
|
|
<application>postgres</application>, unless overridden
|
|
by the <option>-o</option> option. The contents of this file
|
|
are also displayed in <option>status</option> mode.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term><filename>postgresql.conf</filename></term>
|
|
|
|
<listitem>
|
|
<para>
|
|
This file, located in the data directory, is parsed to find the
|
|
proper port to use with <application>psql</application>
|
|
when waiting for startup.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
</variablelist>
|
|
</refsect1>
|
|
|
|
|
|
<refsect1>
|
|
<title>Notes</title>
|
|
|
|
<para>
|
|
Waiting for complete startup is not a well-defined operation and might
|
|
fail if access control is set up so that a local client cannot
|
|
connect without manual interaction (e.g., password authentication). For
|
|
additional connection variables, see <xref linkend="libpq-envars">,
|
|
and for passwords, also see <xref linkend="libpq-pgpass">.
|
|
</para>
|
|
</refsect1>
|
|
|
|
|
|
<refsect1 id="R1-APP-PGCTL-2">
|
|
<title>Examples</title>
|
|
|
|
<refsect2 id="R2-APP-PGCTL-3">
|
|
<title>Starting the Server</title>
|
|
|
|
<para>
|
|
To start up a server:
|
|
<screen>
|
|
<prompt>$</prompt> <userinput>pg_ctl start</userinput>
|
|
</screen>
|
|
</para>
|
|
|
|
<para>
|
|
An example of starting the server, blocking until the server has
|
|
come up is:
|
|
<screen>
|
|
<prompt>$</prompt> <userinput>pg_ctl -w start</userinput>
|
|
</screen>
|
|
</para>
|
|
|
|
<para>
|
|
For a server 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 Server</title>
|
|
<para>
|
|
<screen>
|
|
<prompt>$</prompt> <userinput>pg_ctl stop</userinput>
|
|
</screen>
|
|
stops the server. 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 Server</title>
|
|
|
|
<para>
|
|
Restarting the server is almost equivalent to stopping the
|
|
server 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 server in the simplest form, use:
|
|
<screen>
|
|
<prompt>$</prompt> <userinput>pg_ctl restart</userinput>
|
|
</screen>
|
|
</para>
|
|
|
|
<para>
|
|
To restart the server,
|
|
waiting for it to shut down and come up again:
|
|
<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 the Server 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: server is running (pid: 13718)
|
|
Command line was:
|
|
/usr/local/pgsql/bin/postgres '-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>
|
|
|
|
<simplelist type="inline">
|
|
<member><xref linkend="app-initdb"></member>
|
|
<member><xref linkend="app-postgres"></member>
|
|
</simplelist>
|
|
</refsect1>
|
|
|
|
</refentry>
|