DOC HOME SITE MAP MAN PAGES GNU INFO SEARCH PRINT BOOK
 

postgres(1)




POSTGRES(1)      PostgreSQL Server Applications       POSTGRES(1)


NAME

     postgres - PostgreSQL database server


SYNOPSIS

     postgres [ option... ]


DESCRIPTION

     postgres is the PostgreSQL database server. In order  for  a
     client  application to access a database it connects (over a
     network or locally) to  a  running  postgres  process.   The
     postgres  instance  then starts a separate server process to
     handle the connection.

     One postgres instance always manages the data  from  exactly
     one  database cluster. A database cluster is a collection of
     databases that is stored at a common  file  system  location
     (the  ``data area''). More than one postgres process can run
     on a system at one time, so long as they use different  data
     areas  and  different  communication ports (see below). When
     postgres starts it needs to know the location  of  the  data
     area. The location must be specified by the -D option or the
     PGDATA environment variable; there is no default. Typically,
     -D  or  PGDATA  points  directly  to the data area directory
     created by initdb(1). Other possible file layouts  are  dis-
     cussed in in the documentation.

     By default postgres starts in the foreground and prints  log
     messages to the standard error stream. In practical applica-
     tions postgres should be started as  a  background  process,
     perhaps at boot time.

     The postgres command can also be called in single-user mode.
     The  primary  use  for  this mode is during bootstrapping by
     initdb(1). Sometimes it is used for  debugging  or  disaster
     recovery  (but note that running a single-user server is not
     truly suitable for debugging the server, since no  realistic
     interprocess  communication  and locking will happen).  When
     invoked in single-user mode from the  shell,  the  user  can
     enter queries and the results will be printed to the screen,
     but in a form that is more useful for  developers  than  end
     users. In the single-user mode, the session user will be set
     to the user with ID 1, and  implicit  superuser  powers  are
     granted  to  this user.  This user does not actually have to
     exist, so the single-user  mode  can  be  used  to  manually
     recover  from certain kinds of accidental damage to the sys-
     tem catalogs.


OPTIONS

     postgres accepts the following command-line arguments. For a
     detailed discussion of the options consult in the documenta-
     tion. You can save typing most of these options  by  setting

Application          Last change: 2008-01-03                    1

POSTGRES(1)      PostgreSQL Server Applications       POSTGRES(1)

     up a configuration file. Some (safe) options can also be set
     from the connecting client in an  application-dependent  way
     to apply only for that session. For example, if the environ-
     ment variable PGOPTIONS is  set,  then  libpq-based  clients
     will pass that string to the server, which will interpret it
     as postgres command-line options.

  GENERAL PURPOSE
     -A 0|1
          Enables run-time assertion checks, which is a debugging
          aid to detect programming mistakes. This option is only
          available if assertions were  enabled  when  PostgreSQL
          was compiled. If so, the default is on.

     -B nbuffers
          Sets the number of shared buffers for use by the server
          processes.  The  default  value  of  this  parameter is
          chosen automatically by initdb; refer to in  the  docu-
          mentation for more information.

     -c name=value
          Sets a  named  run-time  parameter.  The  configuration
          parameters  supported by PostgreSQL are described in in
          the documentation.  Most  of  the  other  command  line
          options  are  in  fact  short forms of such a parameter
          assignment. -c can appear multiple times to set  multi-
          ple parameters.

     -d debug-level
          Sets the debug level. The higher this value is set, the
          more  debugging  output  is  written to the server log.
          Values are from 1 to 5. It is also possible to pass  -d
          0 for a specific session, which will prevent the server
          log level of the parent  postgres  process  from  being
          propagated to this session.

     -D datadir
          Specifies the file system location of the  data  direc-
          tory or configuration file(s). See in the documentation
          for details.

     -e   Sets the default date style to  ``European'',  that  is
          DMY ordering of input date fields. This also causes the
          day to be printed before the month in certain date out-
          put  formats.  See in the documentation for more infor-
          mation.

     -F   Disables fsync calls for improved performance,  at  the
          risk of data corruption in the event of a system crash.
          Specifying this option is equivalent to  disabling  the
          fsync  configuration parameter. Read the detailed docu-
          mentation before using this!

Application          Last change: 2008-01-03                    2

POSTGRES(1)      PostgreSQL Server Applications       POSTGRES(1)

     -h hostname
          Specifies the IP host name or address on which postgres
          is  to listen for TCP/IP connections from client appli-
          cations. The value can also be a  comma-separated  list
          of  addresses,  or * to specify listening on all avail-
          able interfaces. An empty value specifies not listening
          on  any  IP  addresses,  in which case only Unix-domain
          sockets can be used to connect to the server.  Defaults
          to listening only on localhost.  Specifying this option
          is equivalent to setting  the  listen_addresses  confi-
          guration parameter.

     -i   Allows remote clients to connect via  TCP/IP  (Internet
          domain)  connections.  Without  this option, only local
          connections are accepted. This option is equivalent  to
          setting listen_addresses to * in postgresql.conf or via
          -h.

          This option is  deprecated  since  it  does  not  allow
          access  to  the full functionality of listen_addresses.
          It's usually better to set listen_addresses directly.

     -k directory
          Specifies the directory of the  Unix-domain  socket  on
          which postgres is to listen for connections from client
          applications. The default is normally /tmp, but can  be
          changed at build time.

     -l   Enables secure connections using SSL.  PostgreSQL  must
          have been compiled with support for SSL for this option
          to be available. For more  information  on  using  SSL,
          refer to in the documentation.

     -N max-connections
          Sets the maximum number of client connections that this
          server  will  accept. By default, this value is 32, but
          it can be set as high  as  your  system  will  support.
          (Note  that -B is required to be at least twice -N. See
          in  the  documentation  for  a  discussion  of   system
          resource  requirements for large numbers of client con-
          nections.) Specifying this option is equivalent to set-
          ting the max_connections configuration parameter.

     -o extra-options
          The command  line-style  options  specified  in  extra-
          options  are  passed to all server processes started by
          this postgres process. If the  option  string  contains
          any spaces, the entire string must be quoted.

          The use of this option is  obsolete;  all  command-line
          options  for server processes can be specified directly
          on the postgres command line.

Application          Last change: 2008-01-03                    3

POSTGRES(1)      PostgreSQL Server Applications       POSTGRES(1)

     -p port
          Specifies the TCP/IP port or local Unix  domain  socket
          file  extension on which postgres is to listen for con-
          nections from client  applications.   Defaults  to  the
          value  of the PGPORT environment variable, or if PGPORT
          is not set, then defaults to the value established dur-
          ing  compilation (normally 5432). If you specify a port
          other than the default port, then all  client  applica-
          tions  must specify the same port using either command-
          line options or PGPORT.

     -s   Print time information and other statistics at the  end
          of  each  command.   This is useful for benchmarking or
          for use in tuning the number of buffers.

     -S work-mem
          Specifies the amount of memory to be used  by  internal
          sorts  and  hashes  before  resorting to temporary disk
          files. See the description of the  work_mem  configura-
          tion parameter in in the documentation.

     --name=value
          Sets a named run-time parameter; a shorter form of -c.

     --describe-config
          This option dumps out the server's internal  configura-
          tion  variables,  descriptions,  and  defaults  in tab-
          delimited COPY format.  It is  designed  primarily  for
          use by administration tools.

  SEMI-INTERNAL OPTIONS
     There are several other options that may be specified,  used
     mainly  for  debugging  purposes and in some cases to assist
     with recovery of severely damaged databases. There should be
     no  reason to use them in a production database setup. These
     are listed here  only  for  the  use  by  PostgreSQL  system
     developers.  Furthermore, any of these options may disappear
     or change in a future release without notice.

     -f { s | i | m | n | h }
          Forbids the use of particular scan and join methods:  s
          and  i disable sequential and index scans respectively,
          while n, m, and h disable nested-loop, merge  and  hash
          joins respectively.

          Neither sequential scans nor nested-loop joins  can  be
          disabled  completely;  the  -fs  and -fn options simply
          discourage the optimizer from using those plan types if
          it has any other alternative.

     -n   This option is for  debugging  problems  that  cause  a
          server process to die abnormally. The ordinary strategy

Application          Last change: 2008-01-03                    4

POSTGRES(1)      PostgreSQL Server Applications       POSTGRES(1)

          in  this  situation  is  to  notify  all  other  server
          processes  that they must terminate and then reinitial-
          ize the shared memory and semaphores. This  is  because
          an  errant  server  process  could  have corrupted some
          shared state before terminating. This option  specifies
          that  postgres will not reinitialize shared data struc-
          tures. A knowledgeable system programmer can then use a
          debugger to examine shared memory and semaphore state.

     -O   Allows the structure of system tables to  be  modified.
          This is used by initdb.

     -P   Ignore system indexes when reading system  tables  (but
          still  update  the  indexes when modifying the tables).
          This is useful  when  recovering  from  damaged  system
          indexes.

     -t pa[rser] | pl[anner] | e[xecutor]
          Print timing statistics for each query relating to each
          of the major system modules. This option cannot be used
          together with the -s option.

     -T   This option is for  debugging  problems  that  cause  a
          server process to die abnormally. The ordinary strategy
          in  this  situation  is  to  notify  all  other  server
          processes  that they must terminate and then reinitial-
          ize the shared memory and semaphores. This  is  because
          an  errant  server  process  could  have corrupted some
          shared state before terminating. This option  specifies
          that  postgres  will stop all other server processes by
          sending the signal SIGSTOP, but will not cause them  to
          terminate.  This  permits system programmers to collect
          core dumps from all server processes by hand.

     -v protocol
          Specifies the version number  of  the  frontend/backend
          protocol  to  be  used  for  a particular session. This
          option is for internal use only.

     -W seconds
          A delay of this many seconds occurs when a  new  server
          process  is  started, after it conducts the authentica-
          tion procedure.  This is intended to give an  opportun-
          ity to attach to the server process with a debugger.

     -y database
          Indicates that this is a subprocess started by a parent
          postgres  process,  and  specifies the database to use.
          This option is for internal use only.

  OPTIONS FOR SINGLE-USER MODE

Application          Last change: 2008-01-03                    5

POSTGRES(1)      PostgreSQL Server Applications       POSTGRES(1)

     The following options only apply to the single-user mode.

     --single
          Selects the single-user mode. This must  be  the  first
          argument on the command line.

     database
          Specifies the name of the database to be  accessed.  If
          it is omitted it defaults to the user name.

     -E   Echo all commands.

     -j   Disables use of newline as a statement delimiter.

     -r filename
          Send all server log output to filename. In normal  mul-
          tiuser mode, this option is ignored, and stderr is used
          by all processes.


ENVIRONMENT

     PGCLIENTENCODING
          Default  character  encoding  used  by  clients.   (The
          clients may override this individually.) This value can
          also be set in the configuration file.

     PGDATA
          Default data directory location

     PGDATESTYLE
          Default value of the datestyle run-time parameter. (The
          use of this environment variable is deprecated.)

     PGPORT
          Default port (preferably set in the configuration file)

     TZ   Server time zone


DIAGNOSTICS

     A failure message mentioning semget or shmget probably indi-
     cates  you need to configure your kernel to provide adequate
     shared memory and semaphores. For more discussion see in the
     documentation.  You  may  be  able to postpone reconfiguring
     your kernel  by  decreasing  shared_buffers  to  reduce  the
     shared  memory consumption of PostgreSQL, and/or by reducing
     max_connections to reduce the semaphore consumption.

     A failure message suggesting that another server is  already
     running  should  be  checked carefully, for example by using
     the command

     $ ps ax | grep postgres

Application          Last change: 2008-01-03                    6

POSTGRES(1)      PostgreSQL Server Applications       POSTGRES(1)

     or

     $ ps -ef | grep postgres

     depending on your system. If you are certain  that  no  con-
     flicting  server  is  running,  you may remove the lock file
     mentioned in the message and try again.

     A failure message indicating inability to bind to a port may
     indicate  that  that  port  is  already  in use by some non-
     PostgreSQL process. You may also get this error if you  ter-
     minate  postgres  and  immediately restart it using the same
     port; in this case, you must simply wait a few seconds until
     the  operating  system  closes the port before trying again.
     Finally, you may get this error if you specify a port number
     that  your  operating  system  considers to be reserved. For
     example, many versions of Unix consider port  numbers  under
     1024 to be ``trusted'' and only permit the Unix superuser to
     access them.


NOTES

     If at all possible, do not use  SIGKILL  to  kill  the  main
     postgres server. Doing so will prevent postgres from freeing
     the system resources (e.g., shared  memory  and  semaphores)
     that  it  holds  before terminating. This may cause problems
     for starting a fresh postgres run.

     To terminate  the  postgres  server  normally,  the  signals
     SIGTERM, SIGINT, or SIGQUIT can be used. The first will wait
     for all clients to terminate  before  quitting,  the  second
     will  forcefully  disconnect all clients, and the third will
     quit immediately without proper  shutdown,  resulting  in  a
     recovery  run  during restart. The SIGHUP signal will reload
     the server configuration files. It is also possible to  send
     SIGHUP  to an individual server process, but that is usually
     not sensible.

     The utility command pg_ctl(1) can be used to start and  shut
     down the postgres server safely and comfortably.

     To cancel a running query, send the  SIGINT  signal  to  the
     process running that command.

     The postgres server uses SIGTERM to tell subordinate  server
     processes  to quit normally and SIGQUIT to terminate without
     the normal cleanup.  These signals should  not  be  used  by
     users. It is also unwise to send SIGKILL to a server process
     - the main postgres process will interpret this as  a  crash
     and  will force all the sibling processes to quit as part of
     its standard crash-recovery procedure.

Application          Last change: 2008-01-03                    7

POSTGRES(1)      PostgreSQL Server Applications       POSTGRES(1)


BUGS

     The -- options will not work on FreeBSD or OpenBSD.  Use  -c
     instead.  This is a bug in the affected operating systems; a
     future release of PostgreSQL will provide  a  workaround  if
     this is not fixed.


USAGE

     To start a single-user mode server, use a command like

     postgres --single -D /usr/local/pgsql/data other-options my_database

     Provide the correct path to the database directory with  -D,
     or  make  sure  that the environment variable PGDATA is set.
     Also specify the name of the particular database you want to
     work in.

     Normally, the single-user mode server treats newline as  the
     command  entry  terminator;  there  is no intelligence about
     semicolons, as there is  in  psql.  To  continue  a  command
     across  multiple  lines, you must type backslash just before
     each newline except the last one.

     But if you use the -j command line switch, then newline does
     not  terminate  command entry. In this case, the server will
     read the standard input until the end-of-file (EOF)  marker,
     then   process   the  input  as  a  single  command  string.
     Backslash-newline is not treated specially in this case.

     To quit the session,  type  EOF  (Control+D,  usually).   If
     you've used -j, two consecutive EOFs are needed to exit.

     Note that the  single-user  mode  server  does  not  provide
     sophisticated line-editing features (no command history, for
     example).


EXAMPLES

     To start postgres in the background  using  default  values,
     type:

     $ nohup postgres >logfile 2>&1 </dev/null &

     To start postgres with a specific port:

     $ postgres -p 1234

     This command will start up  postgres  communicating  through
     the  port  1234.  In  order  to connect to this server using
     psql, you would need to run it as

     $ psql -p 1234

Application          Last change: 2008-01-03                    8

POSTGRES(1)      PostgreSQL Server Applications       POSTGRES(1)

     or set the environment variable PGPORT:

     $ export PGPORT=1234
     $ psql

     Named run-time parameters can be  set  in  either  of  these
     styles:

     $ postgres -c work_mem=1234
     $ postgres --work-mem=1234

     Either form  overrides  whatever  setting  might  exist  for
     work_mem  in  postgresql.conf.  Notice  that  underscores in
     parameter names can be written as either underscore or  dash
     on the command line. Except for short-term experiments, it's
     probably  better   practice   to   edit   the   setting   in
     postgresql.conf than to rely on a command-line switch to set
     a parameter.


SEE ALSO

     initdb(1), pg_ctl(1)

Application          Last change: 2008-01-03                    9


Man(1) output converted with man2html