--- /dev/null
+.\" This is -*-nroff-*-
+.\" XXX standard disclaimer belongs here....
+.\" $Header: /cvsroot/pgsql/doc/src/sgml/ref/postgres-ref.sgml,v 1.1 1999/05/26 17:25:38 thomas Exp $
+.TH POSTGRESQL UNIX 05/19/99 PostgreSQL PostgreSQL
+.SH NAME
+postgres - the Postgres backend server
+.SH SYNOPSIS
+.BR "postgres"
+[\c
+.BR "-B"
+n_buffers]
+[\c
+.BR "-C"
+]
+[\c
+.BR "-D"
+data_directory]
+[\c
+.BR "-E"
+]
+[\c
+.BR "-F"
+]
+[\c
+.BR "-O"
+]
+[\c
+.BR "-Q"
+]
+[\c
+.BR "-S kbytes"
+]
+[\c
+.BR "-d"
+debug_level]
+[\c
+.BR "-e"
+]
+[\c
+.BR "-o"
+output_file]
+[\c
+.BR "-s"
+]
+[\c
+.BR "-v protocol"
+]
+[dbname]
+.in -5n
+.SH DESCRIPTION
+The Postgres backend server can be executed directly from the user shell.
+This should be done only while debugging by the DBA, and should not be
+done while other Postgres backends are being managed by a
+.IR postmaster
+on this set of databases.
+.PP
+Some of the switches explained in this man page can be passed to the backend
+through the "database options" field of a connection request, and thus can be
+set for a particular backend without going to the trouble of restarting the
+postmaster. This is particularly handy for debugging-related switches.
+.PP
+The optional argument
+.IR dbname
+specifies the name of the database to be accessed.
+.IR Dbname
+defaults to the value of the
+.SM USER
+environment variable.
+.PP
+The
+.IR postgres
+server understands the following command-line options:
+.TP
+.BR "-B" " n_buffers"
+If the backend is running under the
+.IR postmaster ,
+.IR "n_buffers"
+is the number of shared-memory buffers that the
+.IR "postmaster"
+has allocated for the backend server processes that it starts. If the
+backend is running standalone, this specifies the number of buffers to
+allocate. This value defaults to 64 buffers, where each buffer is 8k bytes
+(or whatever BLCKSZ is set to in config.h).
+.TP
+.BR "-C"
+Do not show server version number.
+.TP
+.BR "-D" " data_directory"
+This option specifies the pathname of the directory that contains the
+database system data (the tables, the catalogs, etc.). If you don't
+specify this option, Postgres uses the value of the PGDATA environment
+variable. You must either specify a -D option or set PGDATA.
+
+The data directory pathname for a database system is normally determined when
+the database system is created with
+.IR initdb ,
+with a --pgdata option to
+.IR initdb .
+.TP
+.BR "-E"
+Echo all queries.
+.TP
+.BR "-F"
+Disable automatic fsync() call after each transaction.
+This option improves performance, but an operating system crash
+while a transaction is in progress will probably cause data loss.
+.TP
+.BR "-O"
+Override restrictions, so system table structures can be modified(pg_*).
+.TP
+.BR "-Q"
+Specifies \*(lqquiet\*(rq mode.
+.TP
+.BR "-S" " kbytes"
+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 -S kilobytes before it starts to put
+data into temporary files.
+.TP
+.BR "-e"
+The
+.IR "-e"
+option controls how dates are input to and output from the database.
+.IP
+If the
+.IR "-e"
+option is supplied, then all dates passed to and from the frontend
+processes will be assumed to be in
+.IR "European"
+format ie.
+.IR "DD-MM-YYYY"
+otherwise dates are input and output in
+.IR "American"
+format ie.
+.IR "MM-DD-YYYY"
+.TP
+.BR "-d" " debug_level"
+Turns on debugging at the numeric level
+.IR "debug_level" .
+Turning on debugging will cause query, parse trees, and query plans to
+be displayed.
+.TP
+.BR "-o" " output_file"
+Sends all debugging and error output to
+.IR output_file .
+If the backend is running under the
+.IR postmaster ,
+error messages are still sent to the frontend process as well as to
+.IR output_file ,
+but debugging output is sent to the controlling tty of the
+.IR postmaster
+(since only one file descriptor can be sent to an actual file).
+.TP
+.BR "-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.
+.TP
+.BR "-v" " protocol"
+Specifies the number of the frontend/backend protocol to be used for this
+particular session.
+.SH "DEVELOPER COMMAND OPTIONS"
+There are several other options that may be specified, used mainly
+for debugging purposes. These are listed here only for the use by
+Postgres system developers.
+.BR "Use of any of these options is highly discouraged" .
+Furthermore, any of these options may disappear or change at any time.
+.TP
+.BR "-A" "n|r|b|Q\fIn\fP|X\fIn\fP"
+.IP
+This option generates a tremendous amount of output.
+.TP
+.BR "-L"
+Turns off the locking system.
+.TP
+.BR "-N"
+Disables use of newline as a query delimiter.
+.TP
+.BR "-f"
+Forbids the use of particular scan and join methods:
+.IR s " and " i
+disable sequential and index scans respectively, while
+.IR 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.)
+.TP
+.BR "-i"
+Prevents query execution, but shows the plan tree.
+.TP
+.BR "-p" " databasename"
+Indicates to the backend server that it has been started by a
+.IR postmaster
+and make different assumptions about buffer pool management, file
+descriptors, etc. Switches following -p are restricted to those
+considered "secure".
+.TP
+.BR "-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 with
+.BR "-s" .
+.SH "SEE ALSO"
+ipcclean(1),
+psql(1),
+postmaster(1).
+.SH "DIAGNOSTICS"
+Of the nigh-infinite number of error messages you may see when you
+execute the backend server directly, the most common will probably be:
+.TP
+.BR "semget: No space left on device"
+If you see this message, you should run the
+.IR ipcclean
+command. After doing this, try starting
+.IR postgres
+again. If this still doesn't work, you probably need to configure
+your kernel for shared memory and semaphores as described in the
+installation notes.
--- /dev/null
+
+
+
+
+ Application
+
+
+
+
+
+ Run the
Postgres multi-user backend
+
+
+
+
+ 1999-05-19
+
+
+postmaster [ -B nBuffers ]
+ [ -D DataDir ] [-N nBackends ] [ -S ]
+ [ -d [ DebugLevel ] ]
+ [ -i ] [ -o BackendOptions ] [ -p port ]
+postmaster [ -n | -s ] ...
+
+
+
+
+ 1999-05-19
+
+
</div>
<div class="diff add">+ Inputs</div>
<div class="diff add">+
+
postmaster accepts the following command line arguments:
+
+
+
+
+ -B nBuffers
+
+
+ The number of shared-memory buffers for the
+ to allocate and manage for the backend server processes that it
+ starts. This value defaults to 64 buffers, where each buffer is 8k bytes
+ (or whatever BLCKSZ is set to in config.h).
+
+
+
+
+
+
+ -D DataDir
+
+
+ Specifies the directory to use as the root of the tree of database
+ directories. If -D is not given, the default data directory name is
+ the value of the environment variable
+ PGDATA.
+ If PGDATA is not set, then the directory used is
+ $POSTGRESHOME/data.
+ If neither environment variable is set and this command-line
+ option is not specified, the default directory that was
+ set at compile-time is used.
+
+
+
+
+
+
+ -N nBackends
+
+
+ The maximum number of backend server processes that this postmaster
+ is allowed to start. In the default configuration, this value
+ is usually set
+ to 32, and can be set as high as 1024 if your system will support that
+ many processes. Both the default and upper limit values can be altered
+ when building
Postgres (see src/include/config.h).
+
+
+
+
+
+
+ -S
+
+
+ Specifies that the
postmaster+ process should start up in silent mode. That is, it will disassociate
+ from the user's (controlling) tty and start its own process group.
+ This should not be used in combination with debugging options because
+ any messages printed to standard output and standard error are
+ discarded.
+
+
+
+
+
+
+ -d [ DebugLevel ]
+
+
+ The optional argument DebugLevel
+ determines the amount of debugging output the backend servers will
+ produce.
+ If DebugLevel
+ is one, the postmaster will trace all connection traffic,
+ and nothing else.
+ For levels two and higher,
+ debugging is turned on in the backend process and the postmaster
+ displays more information,
+ including the backend environment and process traffic.
+ Note that if no file is specified for backend servers to
+ send their debugging output then this output will appear on the
+ controlling tty of their parent
postmaster.
+
+
+
+
+
+
+ -i
+
+
+ This enables TCP/IP or Internet domain socket communication.
+ Without this option, only local Unix domain socket communication is
+ possible.
+
+
+
+
+
+
+ -o BackendOptions
+
+
+ The
+ postgres
+ options specified in
+ BackendOptions
+ are passed to all backend server processes started by this
+ If the option string contains any spaces, the entire string must be
+ quoted.
+
+
+
+
+
+
+ -p port
+
+
+ Specifies the TCP/IP port or local Unix domain socket file extension
+ on which the
postmaster+ is to listen for connections from frontend applications. Defaults to
+ the value of the
+ PGPORT
+ environment variable, or if PGPORT
+ is not set, then defaults to the value established when Postgres was
+ compiled (normally 5432). If you specify a port other than the
+ default port then all frontend applications (including
+
psql) must specify the same
+ port using either command-line options or
+ PGPORT.
+
+
+
+
+
+
+ A few command line options are available for debugging in the case
+ when a backend dies abnormally.
+ These options control the behavior of the
+
postmaster in this situation, and
+ neither option is intended for use in
+ ordinary operation.
+
+
+ The ordinary strategy for this situation is to notify all other
+ backends that they must terminate and then reinitialize the shared
+ memory and semaphores. This is because an errant backend could have
+ corrupted some shared state before terminating.
+
+
+ These special-case options are:
+
+
+
+
+ -n
+
+
+ If the -n
+ option is supplied, then the
+ does not reinitialize shared data structures. A knowledgable system
+ programmer can then use the
+ program to examine shared memory and semaphore state.
+
+
+
+
+
+
+ -s
+
+
+ will stop all other backend processes by sending the signal
+ SIGSTOP,
+ but will not cause them to terminate. This permits system programmers
+ to collect core dumps from all backend processes by hand.
+
+
+
+
+
+
+
+
+
+ 1999-05-19
+
+
</div>
<div class="diff add">+ Outputs</div>
<div class="diff add">+
+
+
+
+
+
+ semget: No space left on device
+
+
+ If you see this message, you should run the
+ command. After doing this, try starting
+ again. If this still doesn't work, you probably need to configure
+ your kernel for shared memory and semaphores as described in the
+ installation notes. If you run multiple instances of
+ on a single host, or have a kernel with particularly small shared memory
+ and/or semaphore limits, you may have to reconfigure your kernel to increase
+ its shared memory or semaphore parameters.
+
+
+ You may be able to postpone
+ reconfiguring your kernel by decreasing -B to reduce
+
Postgres' shared memory
+ consumption, or by reducing -N to reduce Postgres' semaphore
+ consumption.
+
+
+
+
+
+
+
+
+ StreamServerPort: cannot bind to port
+
+
+ If you see this message, you should be certain that there is no other
+ process already running. The easiest way to determine this is by
+ using the command
+% ps -ax | grep postmaster
+
+on BSD-based systems, or
+% ps -e | grep postmast
+
+ for System V-like or POSIX-compliant systems such as HP-UX.
+
+
+ If you
+ are sure that no other
+ processes are running and you still get this error, try specifying a
+ different port using the
+ -p
+ option. You may also get this error if you terminate the
+ 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.
+
+
+
+
+
+
+ IpcMemoryAttach: shmat() failed: Permission denied
+
+
+ A likely explanation is that another user attempted to start a
+ process on the same port which acquired shared resources and then
+ died. Since Postgres shared memory keys are based on the port number
+ assigned to the
+ such conflicts are likely if there is more than one installation on
+ a single host. If there are no other
+ processes currently running (see above), run
+ and try again. If other
postmaster+ images
+ are running, you will have to find the owners of those processes to
+ coordinate the assignment of port numbers and/or removal of unused
+ shared memory segments.
+
+
+
+
+
+
+
+
+
+
+ 1999-05-19
+
+
</div>
<div class="diff add">+ Description</div>
<div class="diff add">+
+
+ manages the communication between frontend and backend processes, as
+ well as allocating the shared buffer pool and SysV semaphores
+ (on machines without a test-and-set instruction).
+ does not itself interact with the user and should be started as a
+ background process.
+
+
+ Only one postmaster should be running at a time in a given
+ Here, an installation means a database directory and
+
postmaster port number.
+ You can run more than one postmaster on a machine only if each one has a
+ separate directory and port number.
+
+
+
+
+ 1998-10-04
+
+
</div>
<div class="diff add">+ Notes</div>
<div class="diff add">+
+
+ If at all possible,
+ do not
+ use SIGKILL
+ when killing the
postmaster.
+ SIGHUP,
+ SIGINT,
+ or
+ SIGTERM
+ (the default signal for
+ should be used instead. Using
+
+% kill -KILL
+
+
+or its alternative form
+
+% kill -9
+
+
+ will prevent
postmaster+ from freeing the system resources (e.g., shared memory and semaphores)
+ that it holds before dying. This prevents you from having to deal with
+ the problem with shared memory described earlier.
+
+
+ Useful utilities for dealing with shared memory problems include
+
+
+
+
+
+ 1998-10-04
+
+
</div>
<div class="diff add">+ Usage</div>
<div class="diff add">+
+ To start
postmaster using default
+ values, type:
+
+% nohup postmaster >logfile 2>&1 &
+
+
+ This command will start up
postmaster+ on the default port (5432). This is the
+ simplest and most common way to start the
+
+
+ To start
postmaster with a specific port
+ and executable name:
+
+% nohup postmaster -p 1234 &
+
+
+ This command will start up
postmaster+ communicating through the port 1234. In order to
+ connect to this
postmaster+ using psql, you would need to run it as
+
+% psql -p 1234
+
+
+ or set the environment variable PGPORT:
+
+% setenv PGPORT 1234
+% psql
+ .
+
+
+
+
+
projects / postgresql.git / commitdiff