<!--
-$Header: /cvsroot/pgsql/doc/src/sgml/ref/pg_ctl-ref.sgml,v 1.3 2000/10/12 22:13:21 momjian Exp $
+$Header: /cvsroot/pgsql/doc/src/sgml/ref/pg_ctl-ref.sgml,v 1.4 2000/11/25 17:17:30 petere Exp $
Postgres documentation
-->
<refentry id="app-pg-ctl">
+ <docinfo>
+ <date>2000-11-25</date>
+ </docinfo>
+
<refmeta>
- <refentrytitle id="app-pg-ctl-title">
- <application>pg_ctl</application>
- </refentrytitle>
+ <refentrytitle id="app-pg-ctl-title"><application>pg_ctl</application></refentrytitle>
+ <manvolnum>1</manvolnum>
<refmiscinfo>Application</refmiscinfo>
</refmeta>
<refnamediv>
- <refname>
- <application>pg_ctl</application>
- </refname>
- <refpurpose>
- Starts, stops, and restarts postmaster
- </refpurpose>
+ <refname>pg_ctl</refname>
+ <refpurpose>Starts, stops, or restarts postmaster</refpurpose>
</refnamediv>
<refsynopsisdiv>
- <refsynopsisdivinfo>
- <date>2000-04-05</date>
- </refsynopsisdivinfo>
-
- <synopsis>
-pg_ctl [-w] [-D <replaceable class="parameter">datadir</replaceable>][-p <replaceable class="parameter">path</replaceable>] [-o "<replaceable class="parameter">options</replaceable>"] start
-pg_ctl [-w] [-D <replaceable class="parameter">datadir</replaceable>] [-m [s[mart]|f[ast]|i[mmediate]]] stop
-pg_ctl [-w] [-D <replaceable class="parameter">datadir</replaceable>] [-m [s[mart]|f[ast]|i[mmediate]]
- [-o "<replaceable class="parameter">options</replaceable>"] restart
-pg_ctl [-D <replaceable class="parameter">datadir</replaceable>] status
- </synopsis>
-
- <refsect2 id="R2-APP-PGCTL-1">
- <title>
- Inputs
- </title>
+ <cmdsynopsis>
+ <command>pg_ctl</command>
+ <arg choice="plain">start</arg>
+ <arg>-w</arg>
+ <arg>-D <replaceable>datadir</replaceable></arg>
+ <arg>-p <replaceable>path</replaceable></arg>
+ <arg>-o <replaceable>options</replaceable></arg>
+ <sbr>
+ <command>pg_ctl</command>
+ <arg choice="plain">stop</arg>
+ <arg>-w</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>-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">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 the <xref linkend="app-postmaster"
+ endterm="app-postmaster-title">, or displaying the status of a
+ running postmaster.
+ </para>
+
+ <refsect2 id="app-pg-ctl-options">
+ <title>Options</title>
<para>
<variablelist>
<term>-w</term>
<listitem>
<para>
- Wait for the database server to come up, by
- watching for creation of the pid file (PGDATA/postmaster.pid).
+ Wait for the database server to come up, by watching for
+ creation of the pid file
+ (<filename><replaceable>PGDATA</replaceable>/postmaster.pid</filename>).
Times out after 60 seconds.
</para>
</listitem>
<term>-D <replaceable class="parameter">datadir</replaceable></term>
<listitem>
<para>
- Specifies the database location for this database installation.
+ Specifies the file system location of the database files. If
+ this is omitted, the environment variable
+ <envar>PGDATA</envar> is used.
</para>
</listitem>
</varlistentry>
<term>-p <replaceable class="parameter">path</replaceable></term>
<listitem>
<para>
- Specifies the path to the postmaster image.
+ 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>-o "<replaceable class="parameter">options</replaceable>"</term>
+ <term>-o <replaceable class="parameter">options</replaceable></term>
<listitem>
<para>
Specifies options to be passed directly to
<term>s</term>
<listitem>
<para>
- smart mode waits for all
- the clients to logout. This is the default.
+ Smart mode waits for all the clients to disconnect. This
+ is the default.
</para>
</listitem>
</varlistentry>
<term>f</term>
<listitem>
<para>
- Fast mode sends SIGTERM to the backends; that means
- active transactions get rolled back.
+ Fast mode does not wait for clients to disconnect. All
+ active transactions will be rolled back.
</para>
</listitem>
</varlistentry>
<term>i</term>
<listitem>
<para>
- Immediate mode sends SIGUSR1
- to the backends and lets them abort. In this case, database recovery
- will be necessary on the next start-up.
+ Immediate mode will abort without complete shutdown. This
+ will lead to a recovery run on restart.
</para>
</listitem>
</varlistentry>
<term>restart</term>
<listitem>
<para>
- Restart the <application>postmaster</application>, performing
- a stop/start sequence.
+ Stop the <application>postmaster</application>, if one is running,
+ and then start it again.
</para>
</listitem>
</varlistentry>
</para>
</refsect2>
- <refsect2 id="R2-APP-PGCTL-2">
- <refsect2info>
- <date>1999-11-07</date>
- </refsect2info>
- <title>
- Outputs
- </title>
- <para>
- <variablelist>
- <varlistentry>
- <term><computeroutput>pg_ctl: postmaster is <replaceable>state</replaceable> (pid: <replaceable>#</replaceable>)</computeroutput></term>
- <listitem>
- <para>
- Postmaster status.
- </para>
- </listitem>
- </varlistentry>
- </variablelist>
+ <refsect2>
+ <title>Files</title>
- If there is an error condition, the backend error message will be displayed.
+ <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>
- </refsynopsisdiv>
- <refsect1 id="R1-APP-PGCTL-1">
- <title>
- Description
- </title>
- <para>
- <application>pg_ctl</application> is a utility for starting,
- stopping or restarting <application>postmaster</application>.
- </para>
</refsect1>
+
<refsect1 id="R1-APP-PGCTL-2">
- <title>
- Usage
- </title>
+ <title>Usage</title>
<refsect2 id="R2-APP-PGCTL-3">
- <title>
- Starting postmaster
- </title>
+ <title>Starting the postmaster</title>
<para>
To start up <application>postmaster</application>:
-
- <programlisting>
-$ pg_ctl start
- </programlisting>
+<screen>
+<prompt>$</prompt> <userinput>pg_ctl start</userinput>
+</screen>
</para>
<para>
- If -w is supplied, pg_ctl waits for the database server to come up, by
- watching for creation of the pid file (PGDATA/postmaster.pid), for up
- to 60 seconds.
- </para>
-
- <para>
- Parameters to invoke <application>postmaster</application> are
- taken from the following sources:
-
- <itemizedlist>
- <listitem>
- <para>
- Path to postmaster: found in the command search path.
- </para>
- </listitem>
-
- <listitem>
- <para>
- Database directory: <envar>PGDATA</envar> environment variable.
- </para>
- </listitem>
-
- <listitem>
- <para>
- Other parameters:
- <filename><envar>PGDATA</envar>/postmaster.opts.default</filename>.
- </para>
- </listitem>
- </itemizedlist>
- </para>
-
- <para>
- <filename>postmaster.opts.default</filename> contains parameters
- for <application>postmaster</application>.
- </para>
-
- <para>
- Note that <filename>postmaster.opts.default</filename> is
- installed by <application>initdb</application> from
- <filename>lib/postmaster.opts.default.sample</filename>
- under the <productname>Postgres</productname> installation
- directory (<filename>lib/postmaster.opts.default.sample</filename>
- is copied from
- <filename>src/bin/pg_ctl/postmaster.opts.default.sample</filename>
- while installing <productname>Postgres</productname>).
- </para>
-
- <para>
- To override the default parameters you can use <option>-D</option>,
- <option>-p</option> and <option>-o</option> options.
- </para>
-
- <para>
- An example of starting the
- <application>postmaster</application>, blocking until
- postmaster comes up is:
- <programlisting>
-$ pg_ctl -w start
- </programlisting>
- </para>
-
- <para>
- To specify the <application>postmaster</application> binary path,
- try:
-
- <programlisting>
-$ pg_ctl -p /usr/local/pgsql/bin/postmaster start
- </programlisting>
+ 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:
-
- <programlisting>
-$ pg_ctl -o "-o -F -p 5433" start
- </programlisting>
+<screen>
+<prompt>$</prompt> <userinput>pg_ctl -o "-F -p 5433" start</userinput>
+</screen>
</para>
</refsect2>
<refsect2 id="R2-APP-PGCTL-4">
- <title>
- Stopping postmaster
- </title>
+ <title>Stopping the postmaster</title>
<para>
-
- <programlisting>
-$ pg_ctl stop
- </programlisting>
-
+<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.
- <option>-w</option>
- waits for postmaster to shut down.
- <option>-m</option> specifies the shut down mode.
+ <option>-w</option> waits for postmaster to shut down.
</para>
</refsect2>
<refsect2 id="R2-APP-PGCTL-5">
- <title>
- Restarting postmaster
- </title>
+ <title>Restarting the postmaster</title>
<para>
This is almost equivalent to stopping the
- <application>postmaster</application> then starting it
- again except that the parameters used before stopping
- it would be used too. This is done by saving them in
- $<envar>PGDATA</envar>/postmaster.opts file.
- <option>-w</option>, <option>-D</option>, <option>-m</option>,
- <option>-fast</option>, <option>-immediate</option> and
- <option>-o</option>
- can also be used in the restarting mode and they have the same meanings as
- described above.
- </para>
-
- <para>
- To restart <application>postmaster</application> in the simplest
- form:
-
- <programlisting>
-$ pg_ctl restart
- </programlisting>
+ <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:
-
- <programlisting>
-$ pg_ctl -w restart
- </programlisting>
+<screen>
+<prompt>$</prompt> <userinput>pg_ctl -w restart</userinput>
+</screen>
</para>
<para>
To restart using port 5433 and disabling fsync after restarting:
-
- <programlisting>
-$ pg_ctl -o "-o -F -p 5433" restart
- </programlisting>
+<screen>
+<prompt>$</prompt> <userinput>pg_ctl -o "-F -p 5433" restart</userinput>
+</screen>
</para>
</refsect2>
<refsect2 id="R2-APP-PGCTL-6">
- <title>
- postmaster status
- </title>
+ <title>Showing postmaster status</title>
<para>
- To get status information from postmaster:
-
- <programlisting>
-$ pg_ctl status
- </programlisting>
- </para>
-
- <para>
- Here is a sample output from <application>pg_ctl</application>:
-
- <programlisting>
+ 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)
-options are:
-/usr/local/src/pgsql/current/bin/postmaster
--p 5433
--D /usr/local/src/pgsql/current/data
--B 64
--b /usr/local/src/pgsql/current/bin/postgres
--N 32
--o '-F'
- </programlisting>
+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>
#
#
# IDENTIFICATION
-# $Header: /cvsroot/pgsql/src/bin/pg_ctl/Attic/pg_ctl.sh,v 1.13 2000/10/24 19:11:15 petere Exp $
+# $Header: /cvsroot/pgsql/src/bin/pg_ctl/Attic/pg_ctl.sh,v 1.14 2000/11/25 17:17:30 petere Exp $
#
#-------------------------------------------------------------------------
+
CMDNAME=`basename $0`
+help="\
+$CMDNAME is a utility to start, stop, restart, and report the status
+of a PostgreSQL server.
+
+Usage:
+ $CMDNAME start [-w] [-D DATADIR] [-p PATH-TO-POSTMASTER] [-o \"OPTIONS\"]
+ $CMDNAME stop [-w] [-D DATADIR] [-m SHUTDOWN-MODE]
+ $CMDNAME restart [-w] [-D DATADIR] [-m SHUTDOWN-MODE] [-o \"OPTIONS\"]
+ $CMDNAME status [-D DATADIR]
+
+Options:
+ -D DATADIR Location of the database storage area
+ -m SHUTDOWN-MODE May be 'smart', 'fast', or 'immediate'
+ -o OPTIONS Command line options to pass to the postmaster
+ (PostgreSQL server executable)
+ -p PATH-TO-POSTMASTER Normally not necessary
+ -w Wait until operation completes
+
+If the -D option is omitted, the environment variable PGDATA is used.
+
+Shutdown modes are:
+ smart Quit after all clients have disconnected
+ fast Quit directly, with proper shutdown
+ immediate Quit without complete shutdown; will lead
+ to recovery run on restart
+
+Report bugs to <pgsql-bugs@postgresql.org>."
+
+advice="\
+Try '$CMDNAME --help' for more information."
+
+
+# Placed here during build
+bindir='@bindir@'
+VERSION='@VERSION@'
+
# Check for echo -n vs echo \c
-ECHO=echo
if echo '\c' | grep -s c >/dev/null 2>&1
then
ECHO_N="echo -n"
#
# Find out where we're located
#
-if $ECHO "$0" | grep '/' > /dev/null 2>&1
+if echo "$0" | grep '/' > /dev/null 2>&1
then
# explicit dir name given
- PGPATH=`$ECHO $0 | sed 's,/[^/]*$,,'` # (dirname command is not portable)
+ self_path=`echo $0 | sed 's,/[^/]*$,,'` # (dirname command is not portable)
else
# look for it in PATH ('which' command is not portable)
- for dir in `$ECHO "$PATH" | sed 's/:/ /g'`
+ for dir in `echo "$PATH" | sed 's/:/ /g'`
do
# empty entry in path means current dir
[ -z "$dir" ] && dir='.'
if [ -f "$dir/$CMDNAME" ]
then
- PGPATH="$dir"
+ self_path="$dir"
break
fi
done
fi
# Check if needed programs actually exist in path
-for prog in postmaster psql
-do
- if [ ! -x "$PGPATH/$prog" ]
- then
- $ECHO "The program $prog needed by $CMDNAME could not be found. It was"
- $ECHO "expected at:"
- $ECHO " $PGPATH/$prog"
- $ECHO "If this is not the correct directory, please start $CMDNAME"
- $ECHO "with a full search path. Otherwise make sure that the program"
- $ECHO "was installed successfully."
- exit 1
- fi
-done
+if [ -x "$self_path/postmaster" ] && [ -x "$self_path/psql" ]; then
+ PGPATH=$self_path
+elif [ -x "$bindir/postmaster" ] && [ -x "$bindir/psql" ]; then
+ PGPATH=$bindir
+else
+ echo "The programs 'postmaster' and 'psql' are needed by $CMDNAME but" 1>&2
+ echo "were not found in the directory '$bindir'." 1>&2
+ echo "Check your installation." 1>&2
+ exit 1
+fi
po_path=$PGPATH/postmaster
while [ "$#" -gt 0 ]
do
case $1 in
- -h|--help)
- usage=1
- break
- ;;
+ -h|--help|-\?)
+ echo "$help"
+ exit 0
+ ;;
+ -V|--version)
+ echo "pg_ctl (PostgreSQL) $VERSION"
+ exit 0
+ ;;
-D)
shift
PGDATA="$1"
- export PGDATA
;;
-p)
shift
sig="-QUIT"
;;
*)
- $ECHO "$CMDNAME: Wrong shutdown mode $sigopt"
- usage=1
+ echo "$CMDNAME: wrong shutdown mode: $1" 1>&2
+ echo "$advice" 1>&2
+ exit 1
;;
esac
;;
shift
POSTOPTS="$1"
;;
+ -*)
+ echo "$CMDNAME: invalid option: $1" 1>&2
+ echo "$advice" 1>&2
+ exit 1
+ ;;
start)
op="start"
;;
op="status"
;;
*)
- usage=1
- break
+ echo "$CMDNAME: invalid operation mode: $1" 1>&2
+ echo "$advice" 1>&2
+ exit 1
;;
esac
shift
done
-if [ "$usage" = 1 -o "$op" = "" ];then
- $ECHO "Usage: $CMDNAME [-w][-D database_dir][-p path_to_postmaster][-o \"postmaster_opts\"] start"
- $ECHO " $CMDNAME [-w][-D database_dir][-m s[mart]|f[ast]|i[mmediate]] stop"
- $ECHO " $CMDNAME [-w][-D database_dir][-m s[mart]|f[ast]|i[mmediate]][-o \"postmaster_opts\"] restart"
- $ECHO " $CMDNAME [-D database_dir] status"
+if [ x"$op" = x"" ];then
+ echo "$CMDNAME: no operation mode specified" 1>&2
+ echo "$advice" 1>&2
exit 1
fi
if [ -z "$PGDATA" ];then
- $ECHO "$CMDNAME: No database directory or environment variable \$PGDATA is specified"
+ echo "$CMDNAME: no database directory or environment variable \$PGDATA is specified" 1>&2
+ echo "$advice" 1>&2
exit 1
fi
PID=`cat $PIDFILE`
if [ $PID -lt 0 ];then
PID=`expr 0 - $PID`
- $ECHO "$CMDNAME: postgres is running (pid: $PID)"
+ echo "$CMDNAME: postgres is running (pid: $PID)"
else
- $ECHO "$CMDNAME: postmaster is running (pid: $PID)"
- $ECHO "options are:"
- $ECHO "`cat $POSTOPTSFILE`"
+ echo "$CMDNAME: postmaster is running (pid: $PID)"
+ echo "Command line was:"
+ echo "`cat $POSTOPTSFILE`"
fi
exit 0
else
- $ECHO "$CMDNAME: postmaster or postgres is not running"
+ echo "$CMDNAME: postmaster or postgres is not running"
exit 1
fi
fi
PID=`cat $PIDFILE`
if [ $PID -lt 0 ];then
PID=`expr 0 - $PID`
- $ECHO "$CMDNAME: Cannot restart postmaster. postgres is running (pid: $PID)"
- $ECHO "Please terminate postgres and try again"
+ echo "$CMDNAME: Cannot restart postmaster. postgres is running (pid: $PID)"
+ echo "Please terminate postgres and try again"
exit 1
fi
# wait for postmaster shutting down
if [ "$wait" = 1 -o $op = "restart" ];then
cnt=0
- $ECHO_N "Waiting for postmaster shutting down.."$ECHO_C
+ $ECHO_N "Waiting for postmaster to shut down.."$ECHO_C
while :
do
$ECHO_N "."$ECHO_C
cnt=`expr $cnt + 1`
if [ $cnt -gt 60 ];then
- $ECHO "$CMDNAME: postmaster does not shut down"
+ echo "$CMDNAME: postmaster does not shut down"
exit 1
fi
else
fi
sleep 1
done
- $ECHO "done."
+ echo "done"
fi
- $ECHO "postmaster successfully shut down."
+ echo "postmaster successfully shut down"
else
- $ECHO "$CMDNAME: Can't find $PIDFILE."
- $ECHO "Is postmaster running?"
+ echo "$CMDNAME: cannot find $PIDFILE"
+ echo "Is postmaster running?"
if [ $op = "restart" ];then
- $ECHO "Anyway, I'm going to start up postmaster..."
+ echo "starting postmaster anyway..."
else
exit 1
fi
if [ $op = "start" -o $op = "restart" ];then
if [ -f $PIDFILE ];then
- $ECHO "$CMDNAME: It seems another postmaster is running. Try to start postmaster anyway."
+ echo "$CMDNAME: It seems another postmaster is running. Trying to start postmaster anyway."
pid=`cat $PIDFILE`
fi
if [ $op = "start" ];then
# if we are in start mode, then look for postmaster.opts.default
if [ -f $DEFPOSTOPTS ];then
- eval "$po_path `cat $DEFPOSTOPTS`" &
+ $po_path -D $PGDATA `cat $DEFPOSTOPTS` &
else
- $po_path &
+ $po_path -D $PGDATA &
fi
else
# if we are in restart mode, then look postmaster.opts
- eval `cat $POSTOPTSFILE` &
+ `cat $POSTOPTSFILE` &
fi
else
- eval "$po_path $POSTOPTS " &
+ # -o given
+ $po_path -D $PGDATA $POSTOPTS &
fi
if [ -f $PIDFILE ];then
if [ "`cat $PIDFILE`" = "$pid" ];then
- $ECHO "$CMDNAME: Cannot start postmaster. Is another postmaster is running?"
+ echo "$CMDNAME: Cannot start postmaster. Is another postmaster is running?"
exit 1
fi
fi
# wait for postmaster starting up
if [ "$wait" = 1 ];then
cnt=0
- $ECHO_N "Waiting for postmaster starting up.."$ECHO_C
+ $ECHO_N "Waiting for postmaster to start up.."$ECHO_C
while :
do
if psql -l >/dev/null 2>&1
$ECHO_N "."$ECHO_C
cnt=`expr $cnt + 1`
if [ $cnt -gt 60 ];then
- $ECHO "$CMDNAME: postmaster does not start up"
+ echo "$CMDNAME: postmaster does not start up"
exit 1
fi
sleep 1
fi
done
- $ECHO "done."
+ echo "done"
fi
- $ECHO "postmaster successfully started up."
+ echo "postmaster successfully started up"
fi
exit 0
projects / postgresql / commitdiff