Description

The postgres executable is the
actual PostgreSQL server process
that processes queries. It is normally not called directly;
instead a postmaster multi-user server is
started.

The second form above is how postgres is invoked by the postmaster (only conceptually, since
both postmaster and postgres are in fact the same program); it should
not be invoked directly this way. The first form invokes the
server directly in interactive single-user mode. The primary use
for this mode is during bootstrapping by initdb. Sometimes it is used for debugging
or disaster recovery.

When invoked in interactive 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. But
note that running a single-user backend is not truly suitable for
debugging the server since no realistic interprocess
communication and locking will happen.

When running a stand-alone backend, the session user will be
set to the user with id 1. This user does not actually have to
exist, so a stand-alone backend can be used to manually recover
from certain kinds of accidental damage to the system catalogs.
Implicit superuser powers are granted to the user with id 1 in
stand-alone mode.

Options

When postgres is started by
a postmaster then it inherits all
options set by the latter. Additionally, postgres-specific options can be passed
from the postmaster with the
-o switch.

You can avoid having to type these options by setting up a
configuration file. See the Administrator's Guide for details. Some (safe)
options can also be set from the connecting client in an
application-dependent way. For example, if the environment
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

The options -A, -B, -c,
-d, -D, -F, and
--name have the same meanings as
for the postmaster.

-e

Sets the default date style to "European", which means that the
"day before month" (rather
than month before day) rule is used to interpret
ambiguous date input, and that the day is printed
before the month in certain date output formats. See
the PostgreSQL User's Guide
for more information.

-o filename

Sends all debugging and error output to filename. If the backend is
running under the postmaster, this option is
ignored, and the stderr inherited from the postmaster is used.

-P

Ignore system indexes while scanning/updating system
tuples. The REINDEX command for
system tables/indexes requires this option to be
used.

-s

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

-S sort-mem

Specifies the amount of memory to be used by
internal sorts and hashes before resorting to temporary
disk files. The value is specified in kilobytes, and
defaults to 512 kilobytes. Note that for a complex
query, several sorts and/or hashes might be running in
parallel, and each one will be allowed to use as much
as sort-mem kilobytes
before it starts to put data into temporary files.

Options for stand-alone mode

database

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

-E

Echo all queries.

-N

Disables use of newline as a query delimiter.

Semi-internal Options

There are several other options that may be specified,
used mainly for debugging purposes. These are listed here
only for the use by PostgreSQL system developers.
Use of any of these
options is highly discouraged. 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.

Note: 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.

-i

Prevents query execution, but shows the plan
tree.

-O

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

-p database

Indicates that this server has been started by a
postmaster and makes
different assumptions about buffer pool management,
file descriptors, etc.

-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.

-v protocol

Specifies the version number of the frontend/backend
protocol to be used for this particular session.

-W seconds

As soon as this option is encountered, the process
sleeps for the specified amount of seconds. This gives
developers time to attach a debugger to the backend
process.

Usage

Start a stand-alone backend with a command like

postgres -D $PGDATA other-options my_database

Provide the correct path to the database area 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 stand-alone backend 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 -N command line
switch, then newline does not terminate command entry. The
backend will read the standard input until the end-of-file (EOF)
marker, then process the input as a single query string.
Backslash-newline is not treated specially in this case.

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

Note that the stand-alone backend does not provide
sophisticated line-editing features (no command history, for
example).