From 8a9315ca92804bd32b3ee864bf83d98840e1a947 Mon Sep 17 00:00:00 2001 From: Peter Eisentraut Date: Tue, 14 Nov 2000 18:11:32 +0000 Subject: Update and polish postmaster and postgres help output and man pages. --- doc/src/sgml/ref/postgres-ref.sgml | 511 ++++++++++++++++--------------------- 1 file changed, 219 insertions(+), 292 deletions(-) (limited to 'doc/src/sgml/ref/postgres-ref.sgml') diff --git a/doc/src/sgml/ref/postgres-ref.sgml b/doc/src/sgml/ref/postgres-ref.sgml index 4f795665390..be0fa978de4 100644 --- a/doc/src/sgml/ref/postgres-ref.sgml +++ b/doc/src/sgml/ref/postgres-ref.sgml @@ -1,217 +1,159 @@ + + 2000-11-12 + + - - postgres - + postgres + 1 Application + - - postgres - - - Run a Postgres single-user backend - + postgres + Run a PostgreSQL single-user backend + - - 1999-07-20 - - -postgres [ dbname ] -postgres [ -B nBuffers ] [ -C ] [ -D DataDir ] [ -E ] [ -F ] - [ -O ] [ -P ] [ -Q ] [ -S SortSize ] [ -d [ DebugLevel ] ] [ -e ] - [ -o ] [ OutputFile ] [ -s ] [ -v protocol ] [ dbname ] - - - - - 1999-05-19 - - - Inputs - - - postgres accepts the following command line arguments: - - - - dbname - - - The optional argument - dbname - specifies the name of the database to be accessed. - dbname - defaults to the value of the - USER - environment variable. - - - + + + postgres + -A 01 + -B nbuffers + -c name=value + -d debug-level + -D datadir + -e + -E + -fsitnmh + -F + -i + -L + -N + -o file-name + -O + -P + + -s + -tpaplex + + -S sort-mem + -W seconds + database + + + postgres + -A 01 + -B nbuffers + -c name=value + -d debug-level + -D datadir + -e + -fsitnmh + -F + -i + -L + -o file-name + -O + -p database + -P + + -s + -tpaplex + + -S sort-mem + -v protocol-version + -W seconds + + - - -B nBuffers - - - If the backend is running under the - postmaster, - nBuffers - is the number of shared-memory buffers that the - postmaster - has allocated for the backend server processes that it starts. If the - backend is running stand-alone, 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). - - - + + Description - - -C - - - Do not show the server version number. - - - - - - -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. - - - + + The postgres executable is the actual + PostgreSQL server process that processes + queries. The second form above is how + postgres is invoked by the (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 mode. The primary use for this + mode is for bootstrapping by . + - - -E - - - Echo all queries. - - - + + 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 inter-process communication + and locking will happen. + - - -F - - - Disable an automatic fsync() call after each transaction. - This option improves performance, but an operating system crash - while a transaction is in progress may cause the loss of - the most recently entered data. Without the fsync() call - the data is buffered by the operating system, and written to disk sometime later. - - - + + When running a stand-alone backend the session user name will + automatically be set to the current effective Unix user name. If + that user does not exist the server will not start. + - - -O - - - Override restrictions, so system table structures can be modified. - These tables are typically those with a leading - pg_ in the table name. - - - + + Options - - -P - - - Ignore system indexes to scan/update system - tuples. The REINDEX for system tables/indexes - requires this option. System tables are - typically those with a leading pg_ in the - table name. - - - + + When postgres is started by a then it + inherits all options set by the latter. Additionally, + postgres-specific options can be passed + from the postmaster with the + switch. + - - -Q - - - Specifies "quiet" mode. - - - + + 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. + - - -S SortSize - - - 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 - SortSize kilobytes - before it starts to put data into temporary files. - - - + + General Purpose - - -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. - - - + + The options , , + , , , + and have the same meaning as with the . + + -e - This option controls how dates are interpreted upon - input to and output from the database. - If the - option is supplied, then dates passed to and from the frontend - processes will be assumed to be in "European" - format (DD-MM-YYYY), - otherwise dates are assumed to be in - "American" format (MM-DD-YYYY). - Dates are accepted by the backend in a wide variety of formats, - and for input dates this switch mostly affects the interpretation - for ambiguous cases. - See the PostgreSQL User's Guide - for more information. + 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 OutputFile + -o file-name Sends all debugging and error output to @@ -226,6 +168,17 @@ postgres [ -B nBuffers ] [ -C ] [ - + + -P + + + Ignore system indexes to scan/update system tuples. The + REINDEX command for system tables/indexes + requires this option to be used. + + + + -s @@ -238,43 +191,42 @@ postgres [ -B nBuffers ] [ -C ] [ - - -v protocol + -S sort-mem - Specifies the number of the frontend/backend protocol to be used for this - particular session. + 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. - - - - 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. - Use of any of these options is highly discouraged. - Furthermore, any of these options may disappear or change at any time. - + + - - These special-case options are: + + Options for stand-alone mode - -A [ n | r | b | Q | X ] + database - This option generates a tremendous amount of output. + Specifies the name of the database to be accessed. If it is + omitted it defaults to the user name. - - + + - -L + -E - Turns off the locking system. + Echo all queries. @@ -287,6 +239,21 @@ postgres [ -B nBuffers ] [ -C ] [ - + + + + + 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 ] @@ -320,123 +287,83 @@ postgres [ -B nBuffers ] [ -C ] [ - - -p dbname + -L - Indicates to the backend server that it has been started by a - postmaster - and makes different assumptions about buffer pool management, file - descriptors, etc. Switches following -p are restricted to those - considered "secure". + Turns off the locking system. - -t pa[rser] | pl[anner] | e[xecutor] + -O - Print timing statistics for each query relating to each of the major - system modules. This option cannot be used with . + Allows the structure of system tables to be modified. This is + used by initdb. - - - - - - 1999-05-19 - - - Outputs - - - Of the nigh-infinite number of error messages you may see when you - execute the backend server directly, the most common will probably be: + + -p database + + + Indicates that this server has been started by a + postmaster and makes different + assumptions about buffer pool management, file descriptors, + etc. + + + - - -semget: No space left on device - + -t pa[rser] | pl[anner] | e[xecutor] - 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 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. + Print timing statistics for each query relating to each of the + major system modules. This option cannot be used together + with the option. + + + - - - You may be able to postpone - reconfiguring your kernel by decreasing -B to reduce - Postgres' shared memory - consumption. - - + + -v protocol + + + Specifies the version number of the frontend/backend protocol + to be used for this particular session. - - - - - - - 1999-05-19 - - - Description - + + -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. + + + - - 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 - postmaster - on this set of databases. - + + + + - - Some of the switches explained here 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. - + + See also - The optional argument dbname - specifies the name of the database to be accessed. - dbname - defaults to the value of the - USER environment variable. + , + , + - - - 1998-10-04 - - - Notes - - - - Useful utilities for dealing with shared memory problems include - ipcs(1), - ipcrm(1), and - ipcclean(1). - See also . - -