From ff8bf5a0ef06886390d63de79776b2558cd230ec Mon Sep 17 00:00:00 2001 From: "Thomas G. Lockhart" <lockhart@fourpalms.org> 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 00000000000..ff3b3329524 --- /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 00000000000..16f318c8143 --- /dev/null +++ b/doc/src/sgml/ref/postmaster.sgml @@ -0,0 +1,500 @@ +<refentry id="APP-POSTMASTER"> + <refmeta> + <refentrytitle> + <application>postmaster</application> + </refentrytitle> + <refmiscinfo>Application</refmiscinfo> + </refmeta> + <refnamediv> + <refname id="postmaster"> + <application>postmaster</application> + </refname> + <refpurpose> + Run the <productname>Postgres</productname> multi-user backend + </refpurpose> + </refnamediv> + <refsynopsisdiv> + <refsynopsisdivinfo> + <date>1999-05-19</date> + </refsynopsisdivinfo> + <synopsis> +postmaster [ -B <replaceable class="parameter">nBuffers</replaceable> ] + [ -D <replaceable class="parameter">DataDir</replaceable> ] [-N <replaceable class="parameter">nBackends</replaceable> ] [ -S ] + [ -d [ <replaceable class="parameter">DebugLevel</replaceable> ] ] + [ -i ] [ -o <replaceable class="parameter">BackendOptions</replaceable> ] [ -p <replaceable class="parameter">port</replaceable> ] +postmaster [ -n | -s ] ... + </synopsis> + + <refsect2 id="R2-APP-POSTMASTER-1"> + <refsect2info> + <date>1999-05-19</date> + </refsect2info> + <title> + Inputs + </title> + <para> + <application>postmaster</application> accepts the following command line arguments: + + <variablelist> + <varlistentry> + <term> + -B <replaceable class="parameter">nBuffers</replaceable> + </term> + <listitem> + <para> + The number of shared-memory buffers for the + <application>postmaster</application> + 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). + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term> + -D <replaceable class="parameter">DataDir</replaceable> + </term> + <listitem> + <para> + 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 + <envar>PGDATA</envar>. + If <envar>PGDATA</envar> is not set, then the directory used is + <filename>$POSTGRESHOME/data</filename>. + 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. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term> + -N <replaceable class="parameter">nBackends</replaceable> + </term> + <listitem> + <para> + 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 <productname>Postgres</productname> (see src/include/config.h). + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term> + -S + </term> + <listitem> + <para> + Specifies that the <application>postmaster</application> + 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. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term> + -d [ <replaceable class="parameter">DebugLevel</replaceable> ] + </term> + <listitem> + <para> + The optional argument <replaceable class="parameter">DebugLevel</replaceable> + determines the amount of debugging output the backend servers will + produce. + If <replaceable class="parameter">DebugLevel</replaceable> + 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 <application>postmaster</application>. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term> + -i + </term> + <listitem> + <para> + This enables TCP/IP or Internet domain socket communication. + Without this option, only local Unix domain socket communication is + possible. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term> + -o <replaceable class="parameter">BackendOptions</replaceable> + </term> + <listitem> + <para> + The + <literal>postgres</literal> + options specified in + <replaceable class="parameter">BackendOptions</replaceable> + are passed to all backend server processes started by this + <application>postmaster</application>. + If the option string contains any spaces, the entire string must be + quoted. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term> + -p <replaceable class="parameter">port</replaceable> + </term> + <listitem> + <para> + Specifies the TCP/IP port or local Unix domain socket file extension + on which the <application>postmaster</application> + is to listen for connections from frontend applications. Defaults to + the value of the + <envar>PGPORT</envar> + environment variable, or if <envar>PGPORT</envar> + 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 + <application>psql</application>) must specify the same + port using either command-line options or + <envar>PGPORT</envar>. + </para> + </listitem> + </varlistentry> + </variablelist> + </para> + + <para> + A few command line options are available for debugging in the case + when a backend dies abnormally. + These options control the behavior of the + <application>postmaster</application> in this situation, and + <emphasis>neither option is intended for use in + ordinary operation</emphasis>. + </para> + + <para> + 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. + </para> + + <para> + These special-case options are: + + <variablelist> + <varlistentry> + <term> + -n + </term> + <listitem> + <para> + If the <literal>-n</literal> + option is supplied, then the + <application>postmaster</application> + does not reinitialize shared data structures. A knowledgable system + programmer can then use the + <application>shmemdoc</application> + program to examine shared memory and semaphore state. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term> + -s + </term> + <listitem> + <para> + <application>postmaster</application> + will stop all other backend processes by sending the signal + <literal>SIGSTOP</literal>, + but will not cause them to terminate. This permits system programmers + to collect core dumps from all backend processes by hand. + </para> + </listitem> + </varlistentry> + </variablelist> + </para> + </refsect2> + + <refsect2 id="R2-APP-POSTMASTER-1"> + <refsect2info> + <date>1999-05-19</date> + </refsect2info> + <title> + Outputs + </title> + <para> + + <variablelist> + <!-- + <varlistentry> + <term> + FindBackend: could not find a backend to execute... + </term> + <listitem> + <para> + If you see this message, you do not have the + <application>postgres</application> + executable in your path. Add the directory in which + <application>postgres</application> resides to + your path. + </para> + </listitem> + </varlistentry> + --> + <varlistentry> + <term> + semget: No space left on device + </term> + <listitem> + <para> + If you see this message, you should run the + <application>ipcclean</application> + command. After doing this, try starting + <application>postmaster</application> + 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 + <application>postmaster</application> + 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. + + <tip> + <para> + You may be able to postpone + reconfiguring your kernel by decreasing -B to reduce + <productname>Postgres</productname>' shared memory + consumption, or by reducing -N to reduce Postgres' semaphore + consumption. + </para> + </tip> + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term> + StreamServerPort: cannot bind to port + </term> + <listitem> + <para> + If you see this message, you should be certain that there is no other + <application>postmaster</application> + process already running. The easiest way to determine this is by + using the command + <programlisting> +% ps -ax | grep postmaster + </programlisting> +on BSD-based systems, or + <programlisting> +% ps -e | grep postmast + </programlisting> + for System V-like or POSIX-compliant systems such as HP-UX. + </para> + + <para> + If you + are sure that no other + <application>postmaster</application> + processes are running and you still get this error, try specifying a + different port using the + <literal>-p</literal> + option. You may also get this error if you terminate the + <application>postmaster</application> + 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 <firstterm>trusted</firstterm> + and only permit the Unix superuser to access them. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term> + IpcMemoryAttach: shmat() failed: Permission denied + </term> + <listitem> + <para> + A likely explanation is that another user attempted to start a + <application>postmaster</application> + 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 + <application>postmaster</application>, + such conflicts are likely if there is more than one installation on + a single host. If there are no other + <application>postmaster</application> + processes currently running (see above), run + <application>ipcclean</application> + and try again. If other <application>postmaster</application> + 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. + </para> + </listitem> + </varlistentry> + </variablelist> + </para> + </refsect2> + </refsynopsisdiv> + + <refsect1 id="R1-APP-POSTMASTER-1"> + <refsect1info> + <date>1999-05-19</date> + </refsect1info> + <title> + Description + </title> + + <para> + <application>postmaster</application> + 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). + <application>postmaster</application> + does not itself interact with the user and should be started as a + background process. + </para> + + <para> + <emphasis>Only one postmaster should be running at a time in a given + <productname>Postgres</productname> installation.</emphasis> + Here, an installation means a database directory and + <application>postmaster</application> port number. + You can run more than one postmaster on a machine only if each one has a + separate directory and port number. + </para> + + <refsect1 id="R1-APP-VACUUMDB-2"> + <refsect1info> + <date>1998-10-04</date> + </refsect1info> + <title> + Notes + </title> + + <para> + If at all possible, + <emphasis>do not</emphasis> + use <literal>SIGKILL</literal> + when killing the <application>postmaster</application>. + <literal>SIGHUP</literal>, + <literal>SIGINT</literal>, + or + <literal>SIGTERM</literal> + (the default signal for + <application>kill</application>(1))" + should be used instead. Using + + <programlisting> +% kill -KILL + </programlisting> + +or its alternative form + + <programlisting> +% kill -9 + </programlisting> + + will prevent <application>postmaster</application> + 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. + </para> + + <para> + Useful utilities for dealing with shared memory problems include + <application>ipcs(1)</application>, + <application>ipcrm(1</application>), and + <application>ipcclean(1)</application>. + </para> + </refsect1> + + <refsect1 id="R1-APP-VACUUMDB-3"> + <refsect1info> + <date>1998-10-04</date> + </refsect1info> + <title> + Usage + </title> + <para> + To start <application>postmaster</application> using default + values, type: + + <programlisting> +% nohup postmaster >logfile 2>&1 & + </programlisting> + + This command will start up <application>postmaster</application> + on the default port (5432). This is the + simplest and most common way to start the + <application>postmaster</application>. + </para> + + <para> + To start <application>postmaster</application> with a specific port + and executable name: + + <programlisting> +% nohup postmaster -p 1234 & + </programlisting> + + This command will start up <application>postmaster</application> + communicating through the port 1234. In order to + connect to this <application>postmaster</application> + using psql, you would need to run it as + + <programlisting> +% psql -p 1234 + </programlisting> + + or set the environment variable <envar>PGPORT</envar>: + + <programlisting> +% setenv PGPORT 1234 +% psql + </programlisting>. + + </refsect1> +</refentry> + +<!-- Keep this comment at the end of the file +Local variables: +mode: sgml +sgml-omittag:nil +sgml-shorttag:t +sgml-minimize-attributes:nil +sgml-always-quote-attributes:t +sgml-indent-step:1 +sgml-indent-data:t +sgml-parent-document:nil +sgml-default-dtd-file:"../reference.ced" +sgml-exposed-tags:nil +sgml-local-catalogs:"/usr/lib/sgml/catalog" +sgml-local-ecat-files:nil +End: +--> -- GitLab