<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd"> <HTML ><HEAD ><TITLE >pg_ctl</TITLE ><META NAME="GENERATOR" CONTENT="Modular DocBook HTML Stylesheet Version 1.79"><LINK REV="MADE" HREF="mailto:pgsql-docs@postgresql.org"><LINK REL="HOME" TITLE="PostgreSQL 8.0.11 Documentation" HREF="index.html"><LINK REL="UP" TITLE="PostgreSQL Server Applications" HREF="reference-server.html"><LINK REL="PREVIOUS" TITLE="pg_controldata" HREF="app-pgcontroldata.html"><LINK REL="NEXT" TITLE="pg_resetxlog" HREF="app-pgresetxlog.html"><LINK REL="STYLESHEET" TYPE="text/css" HREF="stylesheet.css"><META HTTP-EQUIV="Content-Type" CONTENT="text/html; charset=ISO-8859-1"><META NAME="creation" CONTENT="2007-02-02T03:57:22"></HEAD ><BODY CLASS="REFENTRY" ><DIV CLASS="NAVHEADER" ><TABLE SUMMARY="Header navigation table" WIDTH="100%" BORDER="0" CELLPADDING="0" CELLSPACING="0" ><TR ><TH COLSPAN="5" ALIGN="center" VALIGN="bottom" >PostgreSQL 8.0.11 Documentation</TH ></TR ><TR ><TD WIDTH="10%" ALIGN="left" VALIGN="top" ><A HREF="app-pgcontroldata.html" ACCESSKEY="P" >Prev</A ></TD ><TD WIDTH="10%" ALIGN="left" VALIGN="top" ><A HREF="app-pgcontroldata.html" >Fast Backward</A ></TD ><TD WIDTH="60%" ALIGN="center" VALIGN="bottom" ></TD ><TD WIDTH="10%" ALIGN="right" VALIGN="top" ><A HREF="app-pgresetxlog.html" >Fast Forward</A ></TD ><TD WIDTH="10%" ALIGN="right" VALIGN="top" ><A HREF="app-pgresetxlog.html" ACCESSKEY="N" >Next</A ></TD ></TR ></TABLE ><HR ALIGN="LEFT" WIDTH="100%"></DIV ><H1 ><A NAME="APP-PG-CTL" ></A ><SPAN CLASS="APPLICATION" >pg_ctl</SPAN ></H1 ><DIV CLASS="REFNAMEDIV" ><A NAME="AEN50521" ></A ><H2 >Name</H2 >pg_ctl -- start, stop, or restart a <SPAN CLASS="PRODUCTNAME" >PostgreSQL</SPAN > server</DIV ><A NAME="AEN50525" ></A ><DIV CLASS="REFSYNOPSISDIV" ><A NAME="AEN50527" ></A ><H2 >Synopsis</H2 ><P ><TT CLASS="COMMAND" >pg_ctl</TT > start [-w] [-s] [-D <TT CLASS="REPLACEABLE" ><I >datadir</I ></TT >] [-l <TT CLASS="REPLACEABLE" ><I >filename</I ></TT >] [-o <TT CLASS="REPLACEABLE" ><I >options</I ></TT >] [-p <TT CLASS="REPLACEABLE" ><I >path</I ></TT >]<BR><TT CLASS="COMMAND" >pg_ctl</TT > stop [-W] [-s] [-D <TT CLASS="REPLACEABLE" ><I >datadir</I ></TT >] [-m s[mart] | f[ast] | i[mmediate] ]<BR><TT CLASS="COMMAND" >pg_ctl</TT > restart [-w] [-s] [-D <TT CLASS="REPLACEABLE" ><I >datadir</I ></TT >] [-m s[mart] | f[ast] | i[mmediate] ] [-o <TT CLASS="REPLACEABLE" ><I >options</I ></TT >]<BR><TT CLASS="COMMAND" >pg_ctl</TT > reload [-s] [-D <TT CLASS="REPLACEABLE" ><I >datadir</I ></TT >]<BR><TT CLASS="COMMAND" >pg_ctl</TT > status [-D <TT CLASS="REPLACEABLE" ><I >datadir</I ></TT >]<BR><TT CLASS="COMMAND" >pg_ctl</TT > kill [<TT CLASS="REPLACEABLE" ><I >signal_name</I ></TT >] [<TT CLASS="REPLACEABLE" ><I >process_id</I ></TT >]<BR><TT CLASS="COMMAND" >pg_ctl</TT > register [-N <TT CLASS="REPLACEABLE" ><I >servicename</I ></TT >] [-U <TT CLASS="REPLACEABLE" ><I >username</I ></TT >] [-P <TT CLASS="REPLACEABLE" ><I >password</I ></TT >] [-D <TT CLASS="REPLACEABLE" ><I >datadir</I ></TT >] [-w] [-o <TT CLASS="REPLACEABLE" ><I >options</I ></TT >]<BR><TT CLASS="COMMAND" >pg_ctl</TT > unregister [-N <TT CLASS="REPLACEABLE" ><I >servicename</I ></TT >]</P ></DIV ><DIV CLASS="REFSECT1" ><A NAME="APP-PG-CTL-DESCRIPTION" ></A ><H2 >Description</H2 ><P > <SPAN CLASS="APPLICATION" >pg_ctl</SPAN > is a utility for starting, stopping, or restarting the <SPAN CLASS="PRODUCTNAME" >PostgreSQL</SPAN > backend server (<A HREF="app-postmaster.html" ><SPAN CLASS="APPLICATION" >postmaster</SPAN ></A >), or displaying the status of a running server. Although the server can be started manually, <SPAN CLASS="APPLICATION" >pg_ctl</SPAN > encapsulates tasks such as redirecting log output and properly detaching from the terminal and process group. It also provides convenient options for controlled shutdown. </P ><P > In <TT CLASS="OPTION" >start</TT > mode, a new server is launched. The server is started in the background, and standard input is attached to <TT CLASS="FILENAME" >/dev/null</TT >. The standard output and standard error are either appended to a log file (if the <TT CLASS="OPTION" >-l</TT > option is used), or redirected to <SPAN CLASS="APPLICATION" >pg_ctl</SPAN >'s standard output (not standard error). If no log file is chosen, the standard output of <SPAN CLASS="APPLICATION" >pg_ctl</SPAN > should be redirected to a file or piped to another process such as a log rotating program like <SPAN CLASS="APPLICATION" >rotatelogs</SPAN >; otherwise the <TT CLASS="COMMAND" >postmaster</TT > will write its output to the controlling terminal (from the background) and will not leave the shell's process group. </P ><P > In <TT CLASS="OPTION" >stop</TT > mode, the server that is running in the specified data directory is shut down. Three different shutdown methods can be selected with the <TT CLASS="OPTION" >-m</TT > option: <SPAN CLASS="QUOTE" >"Smart"</SPAN > mode waits for all the clients to disconnect. This is the default. <SPAN CLASS="QUOTE" >"Fast"</SPAN > 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. <SPAN CLASS="QUOTE" >"Immediate"</SPAN > mode will abort all server processes without a clean shutdown. This will lead to a recovery run on restart. </P ><P > <TT CLASS="OPTION" >restart</TT > mode effectively executes a stop followed by a start. This allows changing the <TT CLASS="COMMAND" >postmaster</TT > command-line options. </P ><P > <TT CLASS="OPTION" >reload</TT > mode simply sends the <TT CLASS="COMMAND" >postmaster</TT > process a <SPAN CLASS="SYSTEMITEM" >SIGHUP</SPAN > signal, causing it to reread its configuration files (<TT CLASS="FILENAME" >postgresql.conf</TT >, <TT CLASS="FILENAME" >pg_hba.conf</TT >, etc.). This allows changing of configuration-file options that do not require a complete restart to take effect. </P ><P > <TT CLASS="OPTION" >status</TT > mode checks whether a server is running in the specified data directory. If it is, the <ACRONYM CLASS="ACRONYM" >PID</ACRONYM > and the command line options that were used to invoke it are displayed. </P ><P > <TT CLASS="OPTION" >kill</TT > mode allows you to send a signal to a specified process. This is particularly valuable for <SPAN CLASS="PRODUCTNAME" >Microsoft Windows</SPAN > which does not have a <SPAN CLASS="APPLICATION" >kill</SPAN > command. Use <TT CLASS="LITERAL" >--help</TT > to see a list of supported signal names. </P ><P > <TT CLASS="OPTION" >register</TT > mode allows you to register a system service on <SPAN CLASS="PRODUCTNAME" >Microsoft Windows</SPAN >. </P ><P > <TT CLASS="OPTION" >unregister</TT > mode allows you to unregister a system service on <SPAN CLASS="PRODUCTNAME" >Microsoft Windows</SPAN >, previously registered with the <TT CLASS="OPTION" >register</TT > command. </P ></DIV ><DIV CLASS="REFSECT1" ><A NAME="APP-PG-CTL-OPTIONS" ></A ><H2 >Options</H2 ><P > <P ></P ></P><DIV CLASS="VARIABLELIST" ><DL ><DT ><TT CLASS="OPTION" >-D <TT CLASS="REPLACEABLE" ><I >datadir</I ></TT ></TT ></DT ><DD ><P > Specifies the file system location of the database files. If this is omitted, the environment variable <TT CLASS="ENVAR" >PGDATA</TT > is used. </P ></DD ><DT ><TT CLASS="OPTION" >-l <TT CLASS="REPLACEABLE" ><I >filename</I ></TT ></TT ></DT ><DD ><P > Append the server log output to <TT CLASS="REPLACEABLE" ><I >filename</I ></TT >. If the file does not exist, it is created. The <SPAN CLASS="SYSTEMITEM" >umask</SPAN > is set to 077, so access to the log file from other users is disallowed by default. </P ></DD ><DT ><TT CLASS="OPTION" >-m <TT CLASS="REPLACEABLE" ><I >mode</I ></TT ></TT ></DT ><DD ><P > Specifies the shutdown mode. <TT CLASS="REPLACEABLE" ><I >mode</I ></TT > may be <TT CLASS="LITERAL" >smart</TT >, <TT CLASS="LITERAL" >fast</TT >, or <TT CLASS="LITERAL" >immediate</TT >, or the first letter of one of these three. </P ></DD ><DT ><TT CLASS="OPTION" >-o <TT CLASS="REPLACEABLE" ><I >options</I ></TT ></TT ></DT ><DD ><P > Specifies options to be passed directly to the <TT CLASS="COMMAND" >postmaster</TT > command. </P ><P > The options are usually surrounded by single or double quotes to ensure that they are passed through as a group. </P ></DD ><DT ><TT CLASS="OPTION" >-p <TT CLASS="REPLACEABLE" ><I >path</I ></TT ></TT ></DT ><DD ><P > Specifies the location of the <TT CLASS="FILENAME" >postmaster</TT > executable. By default the <TT CLASS="FILENAME" >postmaster</TT > executable is taken from the same directory as <TT CLASS="COMMAND" >pg_ctl</TT >, 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 <TT CLASS="FILENAME" >postmaster</TT > executable was not found. </P ></DD ><DT ><TT CLASS="OPTION" >-s</TT ></DT ><DD ><P > Only print errors, no informational messages. </P ></DD ><DT ><TT CLASS="OPTION" >-w</TT ></DT ><DD ><P > 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 CLASS="ACRONYM" >PID</ACRONYM > file. For starting up, a successful <TT CLASS="COMMAND" >psql -l</TT > indicates success. <TT CLASS="COMMAND" >pg_ctl</TT > will attempt to use the proper port for <SPAN CLASS="APPLICATION" >psql</SPAN >. If the environment variable <TT CLASS="ENVAR" >PGPORT</TT > exists, that is used. Otherwise, it will see if a port has been set in the <TT CLASS="FILENAME" >postgresql.conf</TT > file. If neither of those is used, it will use the default port that <SPAN CLASS="PRODUCTNAME" >PostgreSQL</SPAN > was compiled with (5432 by default). When waiting, <TT CLASS="COMMAND" >pg_ctl</TT > will return an accurate exit code based on the success of the startup or shutdown. </P ></DD ><DT ><TT CLASS="OPTION" >-W</TT ></DT ><DD ><P > Do not wait for start or shutdown to complete. This is the default for starts and restarts. </P ></DD ></DL ></DIV ><P> </P ></DIV ><DIV CLASS="REFSECT1" ><A NAME="APP-PG-CTL-SVCOPTIONS" ></A ><H2 >Windows options</H2 ><P > <P ></P ></P><DIV CLASS="VARIABLELIST" ><DL ><DT ><TT CLASS="OPTION" >-N <TT CLASS="REPLACEABLE" ><I >servicename</I ></TT ></TT ></DT ><DD ><P > Name of the system service to register. The name will be used as both the service name and the display name. </P ></DD ><DT ><TT CLASS="OPTION" >-P <TT CLASS="REPLACEABLE" ><I >password</I ></TT ></TT ></DT ><DD ><P > Password for the user to start the service. </P ></DD ><DT ><TT CLASS="OPTION" >-U <TT CLASS="REPLACEABLE" ><I >username</I ></TT ></TT ></DT ><DD ><P > Username for the user to start the service. For domain users, use the format <TT CLASS="LITERAL" >DOMAIN\username</TT >. </P ></DD ></DL ></DIV ><P> </P ></DIV ><DIV CLASS="REFSECT1" ><A NAME="AEN50742" ></A ><H2 >Environment</H2 ><P ></P ><DIV CLASS="VARIABLELIST" ><DL ><DT ><TT CLASS="ENVAR" >PGDATA</TT ></DT ><DD ><P > Default data directory location. </P ></DD ><DT ><TT CLASS="ENVAR" >PGPORT</TT ></DT ><DD ><P > Default port for <A HREF="app-psql.html" ><SPAN CLASS="APPLICATION" >psql</SPAN ></A > (used by the -w option). </P ></DD ></DL ></DIV ><P > For others, see <A HREF="app-postmaster.html" ><SPAN CLASS="APPLICATION" >postmaster</SPAN ></A >. </P ></DIV ><DIV CLASS="REFSECT1" ><A NAME="AEN50758" ></A ><H2 >Files</H2 ><P ></P ><DIV CLASS="VARIABLELIST" ><DL ><DT ><TT CLASS="FILENAME" >postmaster.pid</TT ></DT ><DD ><P > The existence of this file in the data directory is used to help <SPAN CLASS="APPLICATION" >pg_ctl</SPAN > determine if the server is currently running or not. </P ></DD ><DT ><TT CLASS="FILENAME" >postmaster.opts.default</TT ></DT ><DD ><P > If this file exists in the data directory, <SPAN CLASS="APPLICATION" >pg_ctl</SPAN > (in <TT CLASS="OPTION" >start</TT > mode) will pass the contents of the file as options to the <TT CLASS="COMMAND" >postmaster</TT > command, unless overridden by the <TT CLASS="OPTION" >-o</TT > option. </P ></DD ><DT ><TT CLASS="FILENAME" >postmaster.opts</TT ></DT ><DD ><P >If this file exists in the data directory, <SPAN CLASS="APPLICATION" >pg_ctl</SPAN > (in <TT CLASS="OPTION" >restart</TT > mode) will pass the contents of the file as options to the <SPAN CLASS="APPLICATION" >postmaster</SPAN >, unless overridden by the <TT CLASS="OPTION" >-o</TT > option. The contents of this file are also displayed in <TT CLASS="OPTION" >status</TT > mode. </P ></DD ><DT ><TT CLASS="FILENAME" >postgresql.conf</TT ></DT ><DD ><P > This file, located in the data directory, is parsed to find the proper port to use with <SPAN CLASS="APPLICATION" >psql</SPAN > when the <TT CLASS="OPTION" >-w</TT > is given in <TT CLASS="OPTION" >start</TT > mode. </P ></DD ></DL ></DIV ></DIV ><DIV CLASS="REFSECT1" ><A NAME="AEN50794" ></A ><H2 >Notes</H2 ><P > 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). </P ></DIV ><DIV CLASS="REFSECT1" ><A NAME="R1-APP-PGCTL-2" ></A ><H2 >Examples</H2 ><DIV CLASS="REFSECT2" ><A NAME="R2-APP-PGCTL-3" ></A ><H3 >Starting the Server</H3 ><P > To start up a server: </P><PRE CLASS="SCREEN" ><SAMP CLASS="PROMPT" >$</SAMP > <KBD CLASS="USERINPUT" >pg_ctl start</KBD ></PRE ><P> </P ><P > An example of starting the server, blocking until the server has come up is: </P><PRE CLASS="SCREEN" ><SAMP CLASS="PROMPT" >$</SAMP > <KBD CLASS="USERINPUT" >pg_ctl -w start</KBD ></PRE ><P> </P ><P > For a server using port 5433, and running without <CODE CLASS="FUNCTION" >fsync</CODE >, use: </P><PRE CLASS="SCREEN" ><SAMP CLASS="PROMPT" >$</SAMP > <KBD CLASS="USERINPUT" >pg_ctl -o "-F -p 5433" start</KBD ></PRE ><P> </P ></DIV ><DIV CLASS="REFSECT2" ><A NAME="R2-APP-PGCTL-4" ></A ><H3 >Stopping the Server</H3 ><P ></P><PRE CLASS="SCREEN" ><SAMP CLASS="PROMPT" >$</SAMP > <KBD CLASS="USERINPUT" >pg_ctl stop</KBD ></PRE ><P> stops the server. Using the <TT CLASS="OPTION" >-m</TT > switch allows one to control <SPAN CLASS="emphasis" ><I CLASS="EMPHASIS" >how</I ></SPAN > the backend shuts down. </P ></DIV ><DIV CLASS="REFSECT2" ><A NAME="R2-APP-PGCTL-5" ></A ><H3 >Restarting the Server</H3 ><P > Restarting the server is almost equivalent to stopping the server and starting it again except that <TT CLASS="COMMAND" >pg_ctl</TT > saves and reuses the command line options that were passed to the previously running instance. To restart the server in the simplest form, use: </P><PRE CLASS="SCREEN" ><SAMP CLASS="PROMPT" >$</SAMP > <KBD CLASS="USERINPUT" >pg_ctl restart</KBD ></PRE ><P> </P ><P > To restart server, waiting for it to shut down and to come up: </P><PRE CLASS="SCREEN" ><SAMP CLASS="PROMPT" >$</SAMP > <KBD CLASS="USERINPUT" >pg_ctl -w restart</KBD ></PRE ><P> </P ><P > To restart using port 5433 and disabling <CODE CLASS="FUNCTION" >fsync</CODE > after restarting: </P><PRE CLASS="SCREEN" ><SAMP CLASS="PROMPT" >$</SAMP > <KBD CLASS="USERINPUT" >pg_ctl -o "-F -p 5433" restart</KBD ></PRE ><P> </P ></DIV ><DIV CLASS="REFSECT2" ><A NAME="R2-APP-PGCTL-6" ></A ><H3 >Showing the Server Status</H3 ><P > Here is a sample status output from <SPAN CLASS="APPLICATION" >pg_ctl</SPAN >: </P><PRE CLASS="SCREEN" ><SAMP CLASS="PROMPT" >$</SAMP > <KBD CLASS="USERINPUT" >pg_ctl status</KBD > <SAMP CLASS="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'</SAMP ></PRE ><P> This is the command line that would be invoked in restart mode. </P ></DIV ></DIV ><DIV CLASS="REFSECT1" ><A NAME="AEN50846" ></A ><H2 >See Also</H2 ><P > <A HREF="app-postmaster.html" ><SPAN CLASS="APPLICATION" >postmaster</SPAN ></A > </P ></DIV ><DIV CLASS="NAVFOOTER" ><HR ALIGN="LEFT" WIDTH="100%"><TABLE SUMMARY="Footer navigation table" WIDTH="100%" BORDER="0" CELLPADDING="0" CELLSPACING="0" ><TR ><TD WIDTH="33%" ALIGN="left" VALIGN="top" ><A HREF="app-pgcontroldata.html" ACCESSKEY="P" >Prev</A ></TD ><TD WIDTH="34%" ALIGN="center" VALIGN="top" ><A HREF="index.html" ACCESSKEY="H" >Home</A ></TD ><TD WIDTH="33%" ALIGN="right" VALIGN="top" ><A HREF="app-pgresetxlog.html" ACCESSKEY="N" >Next</A ></TD ></TR ><TR ><TD WIDTH="33%" ALIGN="left" VALIGN="top" ><SPAN CLASS="APPLICATION" >pg_controldata</SPAN ></TD ><TD WIDTH="34%" ALIGN="center" VALIGN="top" ><A HREF="reference-server.html" ACCESSKEY="U" >Up</A ></TD ><TD WIDTH="33%" ALIGN="right" VALIGN="top" ><SPAN CLASS="APPLICATION" >pg_resetxlog</SPAN ></TD ></TR ></TABLE ></DIV ></BODY ></HTML >