From ff8bf5a0ef06886390d63de79776b2558cd230ec Mon Sep 17 00:00:00 2001 From: "Thomas G. Lockhart" Date: Wed, 26 May 1999 17:25:38 +0000 Subject: [PATCH] First copy from the man pages. postgres-ref.sgml is not yet marked up. --- doc/src/sgml/ref/postgres-ref.sgml | 220 +++++++++++++ doc/src/sgml/ref/postmaster.sgml | 500 +++++++++++++++++++++++++++++ 2 files changed, 720 insertions(+) create mode 100644 doc/src/sgml/ref/postgres-ref.sgml create mode 100644 doc/src/sgml/ref/postmaster.sgml diff --git a/doc/src/sgml/ref/postgres-ref.sgml b/doc/src/sgml/ref/postgres-ref.sgml new file mode 100644 index 0000000000..ff3b332952 --- /dev/null +++ b/doc/src/sgml/ref/postgres-ref.sgml @@ -0,0 +1,220 @@ +.\" 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. diff --git a/doc/src/sgml/ref/postmaster.sgml b/doc/src/sgml/ref/postmaster.sgml new file mode 100644 index 0000000000..16f318c814 --- /dev/null +++ b/doc/src/sgml/ref/postmaster.sgml @@ -0,0 +1,500 @@ + + + + postmaster + + Application + + + + postmaster + + + 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 + + + Inputs + + + postmaster accepts the following command line arguments: + + + + + -B nBuffers + + + + The number of shared-memory buffers for the + postmaster + 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 + postmaster. + 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 + postmaster + does not reinitialize shared data structures. A knowledgable system + programmer can then use the + shmemdoc + program to examine shared memory and semaphore state. + + + + + + + -s + + + + postmaster + 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 + + + Outputs + + + + + + + + semget: No space left on device + + + + If you see this message, you should run the + ipcclean + command. After doing this, try starting + postmaster + 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 + postmaster + 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 + postmaster + 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 + postmaster + 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 + postmaster + 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 + postmaster + 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 + postmaster, + such conflicts are likely if there is more than one installation on + a single host. If there are no other + postmaster + processes currently running (see above), run + ipcclean + 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 + + + Description + + + + postmaster + 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). + postmaster + 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 + Postgres installation. + 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 + + + Notes + + + + If at all possible, + do not + use SIGKILL + when killing the postmaster. + SIGHUP, + SIGINT, + or + SIGTERM + (the default signal for + kill(1))" + 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 + ipcs(1), + ipcrm(1), and + ipcclean(1). + + + + + + 1998-10-04 + + + Usage + + + 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 + postmaster. + + + + 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 + . + + + + +