<!-- $Header: /cvsroot/pgsql/doc/src/sgml/ref/pg_ctl-ref.sgml,v 1.9 2001/09/21 21:10:56 tgl Exp $ Postgres documentation --> <refentry id="app-pg-ctl"> <docinfo> <date>2001-02-08</date> </docinfo> <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> encapulates tasks such as redirecting log output, properly detaching from the terminal and process group, and it provides convenient options for controlled shut down. </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 will be rolled back. <quote>Immediate</quote> mode will abort without complete 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 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> <refsect2 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 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 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>-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> <varlistentry> <term>-s</term> <listitem> <para> Only print errors, no informational messages. </para> </listitem> </varlistentry> </variablelist> </para> </refsect2> <refsect2> <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> </refsect2> </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 <application>postmaster</application>: <screen> <prompt>$</prompt> <userinput>pg_ctl start</userinput> </screen> </para> <para> An example of starting the <application>postmaster</application>, blocking until 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 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> then starting it again except that pg_ctl saves and reuses the command line options that were passed to the previously running instance. To restart <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 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>Bugs</title> <para> Waiting for complete start is not a well-defined operation and may fail if access control is set up in way that a local client cannot connect without manual interaction. It should be avoided. </para> </refsect1> <refsect1> <title>See Also</title> <para> <xref linkend="app-postmaster">, <citetitle>PostgreSQL Administrator's Guide</citetitle> </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: -->