DOC HOME SITE MAP MAN PAGES GNU INFO SEARCH PRINT BOOK
 

pg_ctl(1)





NAME

       pg_ctl - start, stop, or restart a PostgreSQL server


SYNOPSIS

       pg_ctl  start  [  -w  ]   [ -s ]  [ -D datadir ]  [ -l filename ]  [ -o
       options ]  [ -p path ]

       pg_ctl stop [ -W ]  [ -s ]  [ -D datadir ]  [ -m
         [ s[mart] ]  [ f[ast] ]  [ i[mmediate] ]
        ]

       pg_ctl restart [ -w ]  [ -s ]  [ -D datadir ]  [ -m
         [ s[mart] ]  [ f[ast] ]  [ i[mmediate] ]
        ]  [ -o options ]

       pg_ctl reload [ -s ]  [ -D datadir ]

       pg_ctl status [ -D datadir ]

       pg_ctl kill [ signal_name ]  [ process_id ]

       pg_ctl register [ -N servicename ]  [ -U username ]  [ -P password ]  [
       -D datadir ]  [ -w ]  [ -o options ]

       pg_ctl unregister [ -N servicename ]


DESCRIPTION

       pg_ctl  is  a  utility  for starting, stopping, or restarting the Post-
       greSQL backend server (postgres(1)), or displaying the status of a run-
       ning server. Although the server can be started manually, pg_ctl encap-
       sulates tasks such as redirecting log  output  and  properly  detaching
       from  the  terminal  and  process  group.  It  also provides convenient
       options for controlled shutdown.

       In start mode, a new server is launched. The server is started  in  the
       background,  and  standard input is attached to /dev/null. The standard
       output and standard error are either appended to a log file (if the  -l
       option  is  used), or redirected to pg_ctl's standard output (not stan-
       dard error). If no log file is chosen, the standard  output  of  pg_ctl
       should  be  redirected  to a file or piped to another process such as a
       log rotating program like rotatelogs; otherwise postgres will write its
       output  to  the controlling terminal (from the background) and will not
       leave the shell's process group.

       In stop mode, the server that is running in the specified  data  direc-
       tory  is  shut  down.  Three different shutdown methods can be selected
       with the -m option: ``Smart'' mode waits for all the clients to discon-
       nect.  This  is the default. ``Fast'' 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. ``Immediate'' mode
       will abort all server processes without a  clean  shutdown.  This  will
       lead to a recovery run on restart.

       restart  mode  effectively  executes  a  stop followed by a start. This
       allows changing the postgres command-line options.

       reload mode simply sends the postgres process a SIGHUP signal,  causing
       it  to  reread  its  configuration files (postgresql.conf, pg_hba.conf,
       etc.). This allows changing of configuration-file options that  do  not
       require a complete restart to take effect.

       status  mode  checks  whether a server is running in the specified data
       directory. If it is, the PID and the command  line  options  that  were
       used to invoke it are displayed.

       kill  mode  allows you to send a signal to a specified process. This is
       particularly valuable for Microsoft Windows which does not have a  kill
       command. Use --help to see a list of supported signal names.

       register mode allows you to register a system service on Microsoft Win-
       dows.

       unregister mode allows you to unregister a system service on  Microsoft
       Windows, previously registered with the register command.


OPTIONS

       -D datadir
              Specifies  the  file  system  location of the database files. If
              this is omitted, the environment variable PGDATA is used.

       -l filename
              Append the server log output to filename. 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.

       -m mode
              Specifies the shutdown mode. mode may be smart, fast, or immedi-
              ate, or the first letter of one of these three.

       -o options
              Specifies options to be passed directly to the postgres command.

              The options are usually surrounded by single or double quotes to
              ensure that they are passed through as a group.

       -p path
              Specifies  the  location  of the postgres executable. By default
              the postgres executable 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 postgres executable
              was not found.

       -s     Only print errors, no informational messages.

       -w     Wait for the start or shutdown to complete. Times out  after  60
              seconds.  This  is the default for shutdowns. A successful shut-
              down is indicated by removal of the PID file. For starting up, a
              successful psql -l indicates success. pg_ctl will attempt to use
              the proper port for psql. If  the  environment  variable  PGPORT
              exists,  that is used. Otherwise, it will see if a port has been
              set in the postgresql.conf file.  If neither of those  is  used,
              it  will  use the default port that PostgreSQL was compiled with
              (5432 by default). When waiting, pg_ctl will return an  accurate
              exit code based on the success of the startup or shutdown.

       -W     Do  not  wait  for  start  or  shutdown to complete. This is the
              default for starts and restarts.

   OPTIONS FOR WINDOWS
       -N servicename
              Name of the system service to register. The name will be used as
              both the service name and the display name.

       -P password
              Password for the user to start the service.

       -U username
              User  name  for the user to start the service. For domain users,
              use the format DOMAIN\username.


ENVIRONMENT

       PGDATA Default data directory location.

       PGPORT Default port for psql(1) (used by the -w option).

       For additional server variables, see postgres(1).  This  utility,  like
       most  other  PostgreSQL  utilities, also uses the environment variables
       supported by libpq (see in the documentation).


FILES

       postmaster.pid
              The existence of this file in the data directory is used to help
              pg_ctl determine if the server is currently running or not.

       postmaster.opts.default
              If  this  file  exists  in  the data directory, pg_ctl (in start
              mode) will pass the contents of the file as options to the post-
              gres command, unless overridden by the -o option.

       postmaster.opts
              If  this  file  exists in the data directory, pg_ctl (in restart
              mode) will pass the contents of the file as options to postgres,
              unless  overridden  by  the -o option. The contents of this file
              are also displayed in status mode.

       postgresql.conf
              This file, located in the data directory, is parsed to find  the
              proper port to use with psql when the -w is given in start mode.


NOTES

       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 with-
       out manual interaction (e.g., password authentication).


EXAMPLES

   STARTING THE SERVER
       To start up a server:

       $ pg_ctl start

       An example of starting the server, blocking until the server  has  come
       up is:

       $ pg_ctl -w start

       For a server using port 5433, and running without fsync, use:

       $ pg_ctl -o "-F -p 5433" start

   STOPPING THE SERVER
       $ pg_ctl stop

       stops  the  server.  Using  the -m switch allows one to control how the
       backend shuts down.

   RESTARTING THE SERVER
       Restarting the server is almost equivalent to stopping the  server  and
       starting  it again except that pg_ctl saves and reuses the command line
       options that were passed to the previously running instance. To restart
       the server in the simplest form, use:

       $ pg_ctl restart

       To restart server, waiting for it to shut down and to come up:

       $ pg_ctl -w restart

       To restart using port 5433 and disabling fsync after restarting:

       $ pg_ctl -o "-F -p 5433" restart

   SHOWING THE SERVER STATUS
       Here is a sample status output from pg_ctl:

       $ pg_ctl status
       pg_ctl: server is running (pid: 13718)
       Command line was:
       /usr/local/pgsql/bin/postgres '-D' '/usr/local/pgsql/data' '-p' '5433' '-B' '128'

       This is the command line that would be invoked in restart mode.


SEE ALSO

       postgres(1)

Application                       2008-06-08                         PG_CTL(1)

Man(1) output converted with man2html