| <!-- |
| $PostgreSQL: pgsql/doc/src/sgml/ref/pg_ctl-ref.sgml,v 1.35.2.2 2007/03/26 17:23:44 tgl 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> |
| |
| <indexterm zone="app-pg-ctl"> |
| <primary>pg_ctl</primary> |
| </indexterm> |
| |
| <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> |
| <sbr> |
| <command>pg_ctl</command> |
| <arg choice="plain">kill</arg> |
| <arg><replaceable>signal_name</replaceable></arg> |
| <arg><replaceable>process_id</replaceable></arg> |
| <sbr> |
| <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>-w</arg> |
| <arg>-o <replaceable>options</replaceable></arg> |
| <sbr> |
| <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 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> |
| In <option>start</option> mode, a new server is launched. The |
| server is started in the background, and standard input is 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 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 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. |
| </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 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 |
| server is shut down. <quote>Immediate</quote> mode will abort |
| all server processes without a 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 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</>. |
| </para> |
| |
| <para> |
| <option>unregister</option> mode allows you to unregister a system service |
| on <productname>Microsoft Windows</>, previously registered with the |
| <option>register</option> command. |
| </para> |
| </refsect1> |
| |
| <refsect1 id="app-pg-ctl-options"> |
| <title>Options</title> |
| |
| <variablelist> |
| <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 from other users is disallowed 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> |
| 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><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 are usually 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> |
| </listitem> |
| </varlistentry> |
| |
| <varlistentry> |
| <term><option>-s</option></term> |
| <listitem> |
| <para> |
| Only print errors, no informational messages. |
| </para> |
| </listitem> |
| </varlistentry> |
| |
| <varlistentry> |
| <term><option>-w</option></term> |
| <listitem> |
| <para> |
| Wait for the start or shutdown to complete. Times out after |
| 60 seconds. This is the default for shutdowns. A successful |
| shutdown is indicated by removal of the <acronym>PID</acronym> |
| file. For starting up, a successful <command>psql -l</command> |
| indicates success. <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, it will see if a port |
| has been set in the <filename>postgresql.conf</filename> file. |
| If neither of those is used, 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 accurate 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 start or shutdown to complete. This is the |
| default for starts and restarts. |
| </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>-P <replaceable class="parameter">password</replaceable></option></term> |
| <listitem> |
| <para> |
| Password for the user to start the service. |
| </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> |
| </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>PGPORT</envar></term> |
| |
| <listitem> |
| <para> |
| Default port for <xref linkend="app-psql"> (used by the -w option). |
| </para> |
| </listitem> |
| </varlistentry> |
| </variablelist> |
| |
| <para> |
| For additional server variables, see <xref linkend="app-postgres">. |
| This utility, like most other <productname>PostgreSQL</> utilities, |
| also uses the environment variables supported by <application>libpq</> |
| (see <xref linkend="libpq-envars">). |
| </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.default</filename></term> |
| |
| <listitem> |
| <para> |
| If this file exists in the data directory, |
| <application>pg_ctl</application> (in <option>start</option> |
| mode) will pass the contents of the file as options to the |
| <command>postgres</command> command, unless overridden by the |
| <option>-o</option> option. |
| </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 the |
| <option>-w</option> is given in <option>start</option> mode. |
| </para> |
| </listitem> |
| </varlistentry> |
| |
| </variablelist> |
| </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 (e.g., password authentication). |
| </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 server, |
| 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 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> |
| |
| <para> |
| <xref linkend="app-postgres"> |
| </para> |
| </refsect1> |
| |
| </refentry> |