diff options
Diffstat (limited to 'doc/src/sgml/ref')
| -rw-r--r-- | doc/src/sgml/ref/alter_database.sgml | 4 | ||||
| -rw-r--r-- | doc/src/sgml/ref/alter_role.sgml | 4 | ||||
| -rw-r--r-- | doc/src/sgml/ref/initdb.sgml | 5 | ||||
| -rw-r--r-- | doc/src/sgml/ref/ipcclean.sgml | 6 | ||||
| -rw-r--r-- | doc/src/sgml/ref/pg_ctl-ref.sgml | 32 | ||||
| -rw-r--r-- | doc/src/sgml/ref/pg_resetxlog.sgml | 5 | ||||
| -rw-r--r-- | doc/src/sgml/ref/postgres-ref.sgml | 775 | ||||
| -rw-r--r-- | doc/src/sgml/ref/postmaster.sgml | 652 | ||||
| -rw-r--r-- | doc/src/sgml/ref/reindex.sgml | 8 | ||||
| -rw-r--r-- | doc/src/sgml/ref/show.sgml | 4 |
10 files changed, 681 insertions, 814 deletions
diff --git a/doc/src/sgml/ref/alter_database.sgml b/doc/src/sgml/ref/alter_database.sgml index 9c19f849f2..de4966614c 100644 --- a/doc/src/sgml/ref/alter_database.sgml +++ b/doc/src/sgml/ref/alter_database.sgml @@ -1,5 +1,5 @@ <!-- -$PostgreSQL: pgsql/doc/src/sgml/ref/alter_database.sgml,v 1.17 2005/10/13 22:44:51 tgl Exp $ +$PostgreSQL: pgsql/doc/src/sgml/ref/alter_database.sgml,v 1.18 2006/06/18 15:38:36 petere Exp $ PostgreSQL documentation --> @@ -55,7 +55,7 @@ ALTER DATABASE <replaceable class="PARAMETER">name</replaceable> OWNER TO <repla database, the specified value becomes the session default value. The database-specific default overrides whatever setting is present in <filename>postgresql.conf</> or has been received from the - <command>postmaster</command> command line. Only the database + <command>postgres</command> command line. Only the database owner or a superuser can change the session defaults for a database. Certain variables cannot be set this way, or can only be set by a superuser. diff --git a/doc/src/sgml/ref/alter_role.sgml b/doc/src/sgml/ref/alter_role.sgml index a70b56eab2..683e0f054e 100644 --- a/doc/src/sgml/ref/alter_role.sgml +++ b/doc/src/sgml/ref/alter_role.sgml @@ -1,5 +1,5 @@ <!-- -$PostgreSQL: pgsql/doc/src/sgml/ref/alter_role.sgml,v 1.5 2006/04/25 14:56:04 momjian Exp $ +$PostgreSQL: pgsql/doc/src/sgml/ref/alter_role.sgml,v 1.6 2006/06/18 15:38:36 petere Exp $ PostgreSQL documentation --> @@ -81,7 +81,7 @@ ALTER ROLE <replaceable class="PARAMETER">name</replaceable> RESET <replaceable> a specified configuration variable. Whenever the role subsequently starts a new session, the specified value becomes the session default, overriding whatever setting is present in <filename>postgresql.conf</> - or has been received from the <command>postmaster</command> command line. + or has been received from the <command>postgres</command> command line. (For a role without <literal>LOGIN</> privilege, session defaults have no effect.) Ordinary roles can change their own session defaults. diff --git a/doc/src/sgml/ref/initdb.sgml b/doc/src/sgml/ref/initdb.sgml index 664a8d8fb5..69e44c6130 100644 --- a/doc/src/sgml/ref/initdb.sgml +++ b/doc/src/sgml/ref/initdb.sgml @@ -1,5 +1,5 @@ <!-- -$PostgreSQL: pgsql/doc/src/sgml/ref/initdb.sgml,v 1.35 2005/06/21 04:02:31 tgl Exp $ +$PostgreSQL: pgsql/doc/src/sgml/ref/initdb.sgml,v 1.36 2006/06/18 15:38:36 petere Exp $ PostgreSQL documentation --> @@ -127,7 +127,7 @@ PostgreSQL documentation <command>initdb</command>, but you can avoid writing it by setting the <envar>PGDATA</envar> environment variable, which can be convenient since the database server - (<command>postmaster</command>) can find the database + (<command>postgres</command>) can find the database directory later by the same variable. </para> </listitem> @@ -287,7 +287,6 @@ PostgreSQL documentation <simplelist type="inline"> <member><xref linkend="app-postgres"></member> - <member><xref linkend="app-postmaster"></member> </simplelist> </refsect1> diff --git a/doc/src/sgml/ref/ipcclean.sgml b/doc/src/sgml/ref/ipcclean.sgml index 1ec6a4c346..4e58258f86 100644 --- a/doc/src/sgml/ref/ipcclean.sgml +++ b/doc/src/sgml/ref/ipcclean.sgml @@ -1,5 +1,5 @@ <!-- -$PostgreSQL: pgsql/doc/src/sgml/ref/ipcclean.sgml,v 1.11 2005/01/04 03:58:16 tgl Exp $ +$PostgreSQL: pgsql/doc/src/sgml/ref/ipcclean.sgml,v 1.12 2006/06/18 15:38:36 petere Exp $ PostgreSQL documentation --> @@ -32,7 +32,7 @@ PostgreSQL documentation semaphore sets owned by the current user. It is intended to be used for cleaning up after a crashed <productname>PostgreSQL</productname> server (<xref - linkend="app-postmaster">). Note that immediately restarting the + linkend="app-postgres">). Note that immediately restarting the server will also clean up shared memory and semaphores, so this command is of little real utility. </para> @@ -53,7 +53,7 @@ PostgreSQL documentation <para> This script is a hack, but in the many years since it was written, no one has come up with an equally effective and portable solution. - Since the <command>postmaster</command> can now clean up by + Since <command>postgres</command> can now clean up by itself, it is unlikely that <command>ipcclean</command> will be improved upon in the future. </para> diff --git a/doc/src/sgml/ref/pg_ctl-ref.sgml b/doc/src/sgml/ref/pg_ctl-ref.sgml index 81fefe5280..d67fad4d2b 100644 --- a/doc/src/sgml/ref/pg_ctl-ref.sgml +++ b/doc/src/sgml/ref/pg_ctl-ref.sgml @@ -1,5 +1,5 @@ <!-- -$PostgreSQL: pgsql/doc/src/sgml/ref/pg_ctl-ref.sgml,v 1.32 2005/11/04 23:14:02 petere Exp $ +$PostgreSQL: pgsql/doc/src/sgml/ref/pg_ctl-ref.sgml,v 1.33 2006/06/18 15:38:36 petere Exp $ PostgreSQL documentation --> @@ -92,7 +92,7 @@ PostgreSQL documentation <para> <application>pg_ctl</application> is a utility for starting, stopping, or restarting the <productname>PostgreSQL</productname> - backend server (<xref linkend="app-postmaster">), or displaying the + backend server (<xref linkend="app-postgres">), or displaying the status of a running server. Although the server can be started manually, <application>pg_ctl</application> encapsulates tasks such as redirecting log output and properly detaching from the terminal @@ -109,7 +109,7 @@ PostgreSQL documentation standard output (not standard error). If no log file is chosen, the standard output of <application>pg_ctl</application> should be redirected to a file or piped to another process such as a log rotating program - like <application>rotatelogs</>; otherwise the <command>postmaster</command> + like <application>rotatelogs</>; otherwise <command>postgres</command> will write its output to the controlling terminal (from the background) and will not leave the shell's process group. </para> @@ -129,13 +129,13 @@ PostgreSQL documentation <para> <option>restart</option> mode effectively executes a stop followed - by a start. This allows changing the <command>postmaster</command> + by a start. This allows changing the <command>postgres</command> command-line options. </para> <para> <option>reload</option> mode simply sends the - <command>postmaster</command> process a <systemitem>SIGHUP</> + <command>postgres</command> process a <systemitem>SIGHUP</> signal, causing it to reread its configuration files (<filename>postgresql.conf</filename>, <filename>pg_hba.conf</filename>, etc.). This allows changing of @@ -215,7 +215,7 @@ PostgreSQL documentation <listitem> <para> Specifies options to be passed directly to the - <command>postmaster</command> command. + <command>postgres</command> command. </para> <para> The options are usually surrounded by single or double @@ -228,12 +228,12 @@ PostgreSQL documentation <term><option>-p <replaceable class="parameter">path</replaceable></option></term> <listitem> <para> - Specifies the location of the <filename>postmaster</filename> - executable. By default the <filename>postmaster</filename> executable is taken from the same + Specifies the location of the <filename>postgres</filename> + executable. By default the <filename>postgres</filename> executable is taken from the same directory as <command>pg_ctl</command>, or failing that, the hard-wired installation directory. It is not necessary to use this option unless you are doing something unusual and get errors - that the <filename>postmaster</filename> executable was not found. + that the <filename>postgres</filename> executable was not found. </para> </listitem> </varlistentry> @@ -344,7 +344,7 @@ PostgreSQL documentation </variablelist> <para> - For others, see <xref linkend="app-postmaster">. + For others, see <xref linkend="app-postgres">. </para> </refsect1> @@ -373,7 +373,7 @@ PostgreSQL documentation If this file exists in the data directory, <application>pg_ctl</application> (in <option>start</option> mode) will pass the contents of the file as options to the - <command>postmaster</command> command, unless overridden by the + <command>postgres</command> command, unless overridden by the <option>-o</option> option. </para> </listitem> @@ -385,8 +385,8 @@ PostgreSQL documentation <listitem> <para>If this file exists in the data directory, <application>pg_ctl</application> (in <option>restart</option> mode) - will pass the contents of the file as options to the - <application>postmaster</application>, unless overridden + will pass the contents of the file as options to + <application>postgres</application>, unless overridden by the <option>-o</option> option. The contents of this file are also displayed in <option>status</option> mode. </para> @@ -500,9 +500,9 @@ PostgreSQL documentation <screen> <prompt>$</prompt> <userinput>pg_ctl status</userinput> <computeroutput> -pg_ctl: postmaster is running (pid: 13718) +pg_ctl: server is running (pid: 13718) Command line was: -/usr/local/pgsql/bin/postmaster '-D' '/usr/local/pgsql/data' '-p' '5433' '-B' '128' +/usr/local/pgsql/bin/postgres '-D' '/usr/local/pgsql/data' '-p' '5433' '-B' '128' </computeroutput> </screen> This is the command line that would be invoked in restart mode. @@ -515,7 +515,7 @@ Command line was: <title>See Also</title> <para> - <xref linkend="app-postmaster"> + <xref linkend="app-postgres"> </para> </refsect1> diff --git a/doc/src/sgml/ref/pg_resetxlog.sgml b/doc/src/sgml/ref/pg_resetxlog.sgml index e407e6c4ef..acdf0c7aed 100644 --- a/doc/src/sgml/ref/pg_resetxlog.sgml +++ b/doc/src/sgml/ref/pg_resetxlog.sgml @@ -1,5 +1,5 @@ <!-- -$PostgreSQL: pgsql/doc/src/sgml/ref/pg_resetxlog.sgml,v 1.15 2006/06/03 02:19:24 momjian Exp $ +$PostgreSQL: pgsql/doc/src/sgml/ref/pg_resetxlog.sgml,v 1.16 2006/06/18 15:38:36 petere Exp $ PostgreSQL documentation --> @@ -168,8 +168,7 @@ PostgreSQL documentation server crashed then a lock file may have been left behind; in that case you can remove the lock file to allow <command>pg_resetxlog</command> to run. But before you do - so, make doubly certain that there - is no <command>postmaster</command> nor any backend server process still alive. + so, make doubly certain that there is no server process still alive. </para> </refsect1> diff --git a/doc/src/sgml/ref/postgres-ref.sgml b/doc/src/sgml/ref/postgres-ref.sgml index 1cf8521beb..bbc3d29e5d 100644 --- a/doc/src/sgml/ref/postgres-ref.sgml +++ b/doc/src/sgml/ref/postgres-ref.sgml @@ -1,29 +1,28 @@ <!-- -$PostgreSQL: pgsql/doc/src/sgml/ref/postgres-ref.sgml,v 1.46 2006/01/05 10:07:44 petere Exp $ +$PostgreSQL: pgsql/doc/src/sgml/ref/postgres-ref.sgml,v 1.47 2006/06/18 15:38:36 petere Exp $ PostgreSQL documentation --> -<refentry id="APP-POSTGRES"> +<refentry id="app-postgres"> <refmeta> - <refentrytitle id="APP-POSTGRES-TITLE"><application>postgres</application></refentrytitle> + <refentrytitle><application>postgres</application></refentrytitle> <manvolnum>1</manvolnum> <refmiscinfo>Application</refmiscinfo> </refmeta> <refnamediv> <refname>postgres</refname> - <refpurpose>run a <productname>PostgreSQL</productname> server in single-user mode</refpurpose> + <refpurpose><productname>PostgreSQL</productname> database server</refpurpose> </refnamediv> <indexterm zone="app-postgres"> - <primary>postgres (the program)</primary> + <primary>postgres</primary> </indexterm> <refsynopsisdiv> <cmdsynopsis> <command>postgres</command> <arg rep="repeat"><replaceable>option</></arg> - <arg choice="plain"><replaceable>database</replaceable></arg> </cmdsynopsis> </refsynopsisdiv> @@ -31,123 +30,337 @@ PostgreSQL documentation <title>Description</title> <para> - The <command>postgres</command> executable is the actual - <productname>PostgreSQL</productname> server process that processes - SQL statements. It is normally not called directly; instead a - <xref linkend="app-postmaster"> multiuser server is started. - Conceptually, the <command>postmaster</command> starts a new - <command>postgres</command> process for each connection. - (<filename>postmaster</filename> and <filename>postgres</filename> - are in fact the same program, and on most platforms the connection - process is forked). + <command>postgres</command> is the + <productname>PostgreSQL</productname> database server. In order + for a client application to access a database it connects (over a + network or locally) to a running <command>postgres</command> process. + The <command>postgres</command> instance then starts a separate server + process to handle the connection. </para> <para> - If the <command>postgres</command> command is called directly, it - invokes the server in interactive single-user mode. The primary - use for this mode is during bootstrapping by <xref - linkend="app-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 server is not truly suitable for - debugging the server since no realistic interprocess communication - and locking will happen. + One <command>postgres</command> instance always manages the data from + exactly one database cluster. A database cluster is a collection + of databases that is stored at a common file system location (the + <quote>data area</quote>). More than one + <command>postgres</command> process can run on a system at one + time, so long as they use different data areas and different + communication ports (see below). When + <command>postgres</command> starts it needs to know the location + of the data area. The location must be specified by the + <option>-D</option> option or the <envar>PGDATA</envar> environment + variable; there is no default. Typically, <option>-D</option> or + <envar>PGDATA</envar> points directly to the data area directory + created by <application>initdb</>. Other possible file layouts are + discussed in <xref linkend="runtime-config-file-locations">. A + data area is created with <xref linkend="app-initdb">. </para> <para> - When running a stand-alone server, the session user will be set to - the user with ID 1. This user does not actually have to exist, so - a stand-alone server can be used to manually recover from certain + By default <command>postgres</command> starts in the + foreground and prints log messages to the standard error stream. In + practical applications the <command>postgres</command> + should be started as a background process, perhaps at boot time. + </para> + + <para> + The <command>postgres</command> command can also be called in + single-user mode. The primary use for this mode is during + bootstrapping by <xref linkend="app-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 + server is not truly suitable for debugging the server since no + realistic interprocess communication and locking will happen. When + running a stand-alone server, the session user will be set to the + user with ID 1. This user does not actually have to exist, so a + stand-alone server 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 + superuser powers are granted to the user with ID 1 in single-user mode. </para> </refsect1> - <refsect1> + <refsect1 id="app-postgres-options"> <title>Options</title> <para> - When <command>postgres</command> is started by a <xref - linkend="app-postmaster"> then it inherits all options set by the - latter. In single-user mode, <command>postgres</command> accepts - all the options that <command>postmaster</command> would accept. - </para> - - <para> - You can avoid having to type these options by setting up a - configuration file. See <xref linkend="runtime-config"> for details. Some - (safe) options can also be set from the connecting client in an - application-dependent way. For example, if the environment - variable <envar>PGOPTIONS</envar> is set, then - <application>libpq</>-based clients will pass that string to the - server, which will interpret it as + <command>postgres</command> accepts the following command-line + arguments. For a detailed discussion of the options consult <xref + linkend="runtime-config">. You can save typing most of these + options by setting up a configuration file. Some (safe) options + can also be set from the connecting client in an + application-dependent way to apply only for that session. For + example, if the environment variable <envar>PGOPTIONS</envar> is + set, then <application>libpq</>-based clients will pass that + string to the server, which will interpret it as <command>postgres</command> command-line options. </para> <refsect2> <title>General Purpose</title> + + <variablelist> + <varlistentry> + <term><option>-A 0|1</option></term> + <listitem> + <para> + Enables run-time assertion checks, which is a debugging aid to + detect programming mistakes. This option is only available if + assertions were enabled when <productname>PostgreSQL</> was + compiled. If so, the default is on. + </para> + </listitem> + </varlistentry> - <para> - The options <option>-A</option>, <option>-B</option>, - <option>-c</option>, <option>-d</option>, <option>-D</option>, - <option>-e</option>, <option>-F</option>, <option>-s</option>, - <option>-S</option>, and <option>--<replaceable>name</></option> - have the same meanings as with the <xref linkend="app-postmaster"> - except that <literal>-d 0</> prevents the server log level of the - <command>postmaster</> from being propagated to - <command>postgres</>. Other <command>postmaster</command> - options are also accepted but will have no noticeable effect - because they only apply to the multiuser server mode, namely - <option>-h</option>, <option>-i</option>, <option>-k</option>, - <option>-l</option>, and <option>-n</option>. - </para> - </refsect2> + <varlistentry> + <term><option>-B <replaceable class="parameter">nbuffers</replaceable></option></term> + <listitem> + <para> + Sets the number of shared buffers for use by the server + processes. The default value of this parameter is chosen + automatically by <application>initdb</application>; refer to <xref + linkend="runtime-config-resource-memory"> for more information. + </para> + </listitem> + </varlistentry> - <refsect2> - <title>Options for stand-alone mode</title> + <varlistentry> + <term><option>-c <replaceable>name</replaceable>=<replaceable>value</replaceable></option></term> + <listitem> + <para> + Sets a named run-time parameter. The configuration parameters + supported by <productname>PostgreSQL</productname> are + described in <xref linkend="runtime-config">. Most of the + other command line options are in fact short forms of such a + parameter assignment. <option>-c</> can appear multiple times + to set multiple parameters. + </para> + </listitem> + </varlistentry> - <variablelist> <varlistentry> - <term><replaceable class="parameter">database</replaceable></term> + <term><option>-d <replaceable>debug-level</replaceable></option></term> <listitem> <para> - Specifies the name of the database to be accessed. If it is - omitted it defaults to the user name. + Sets the debug level. The higher this value is set, the more + debugging output is written to the server log. Values are + from 1 to 5. It is also possible to pass <literal>-d + 0</literal> for a specific session, which will prevent the + server log level of the <command>postgres</> from being + propagated to this session. </para> </listitem> </varlistentry> <varlistentry> - <term><option>-E</option></term> + <term><option>-D <replaceable class="parameter">datadir</replaceable></option></term> <listitem> <para> - Echo all commands. + Specifies the file system location of the data directory or + configuration file(s). See + <xref linkend="runtime-config-file-locations"> for details. </para> </listitem> </varlistentry> <varlistentry> - <term><option>-j</option></term> + <term><option>-e</option></term> <listitem> <para> - Disables use of newline as a statement delimiter. + Sets the default date style to <quote>European</quote>, that is + <literal>DMY</> ordering of input date fields. This also causes + the day to be printed before the month in certain date output formats. + See <xref linkend="datatype-datetime"> for more information. </para> </listitem> </varlistentry> <varlistentry> - <term><option>-r</option> <replaceable class="parameter">filename</replaceable></term> + <term><option>-F</option></term> + <listitem> + <para> + Disables <function>fsync</function> calls for improved + performance, at the risk of data corruption in the event of a + system crash. Specifying this option is equivalent to + disabling the <xref linkend="guc-fsync"> configuration + parameter. Read the detailed documentation before using this! + </para> + + <para> + <option>--fsync=true</option> has the opposite effect + of this option. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term><option>-h <replaceable class="parameter">hostname</replaceable></option></term> + <listitem> + <para> + Specifies the IP host name or address on which + <command>postgres</command> is to listen for TCP/IP + connections from client applications. The value can also be a + comma-separated list of addresses, or <literal>*</> to specify + listening on all available interfaces. An empty value + specifies not listening on any IP addresses, in which case + only Unix-domain sockets can be used to connect to the + <command>postgres</command>. Defaults to listening only on + <systemitem class="systemname">localhost</systemitem>. + Specifying this option is equivalent to setting the <xref + linkend="guc-listen-addresses"> configuration parameter. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term><option>-i</option></term> + <listitem> + <para> + Allows remote clients to connect via TCP/IP (Internet domain) + connections. Without this option, only local connections are + accepted. This option is equivalent to setting + <varname>listen_addresses</> to <literal>*</> in + <filename>postgresql.conf</> or via <option>-h</>. + </para> + <para> + This option is deprecated since it does not allow access to the + full functionality of <xref linkend="guc-listen-addresses">. + It's usually better to set <varname>listen_addresses</> directly. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term><option>-k <replaceable class="parameter">directory</replaceable></option></term> + <listitem> + <para> + Specifies the directory of the Unix-domain socket on which + <command>postgres</command> is to listen for + connections from client applications. The default is normally + <filename>/tmp</filename>, but can be changed at build time. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term><option>-l</option></term> + <listitem> + <para> + Enables secure connections using <acronym>SSL</acronym>. + <productname>PostgreSQL</productname> must have been compiled with + support for <acronym>SSL</acronym> for this option to be + available. For more information on using <acronym>SSL</acronym>, + refer to <xref linkend="ssl-tcp">. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term><option>-N <replaceable class="parameter">max-connections</replaceable></option></term> <listitem> <para> - Send all server log output to - <replaceable class="parameter">filename</replaceable>. - If <command>postgres</command> is running under the - <command>postmaster</command>, this option is ignored, - and the <systemitem>stderr</> inherited from the - <command>postmaster</command> is used. + Sets the maximum number of client connections that this + <command>postgres</command> will accept. By + default, this value is 32, but it can be set as high as your + system will support. (Note that + <option>-B</option> is required to be at least twice + <option>-N</option>. See <xref linkend="kernel-resources"> for a discussion of + system resource requirements for large numbers of client + connections.) Specifying this option is equivalent to setting the + <xref linkend="guc-max-connections"> configuration parameter. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term><option>-o <replaceable class="parameter">extra-options</replaceable></option></term> + <listitem> + <para> + The command line-style options specified in <replaceable + class="parameter">extra-options</replaceable> are passed to + all server processes started by this + <command>postgres</command>. If the option string contains + any spaces, the entire string must be quoted. + </para> + + <para> + The use of this option is obsolete; all command-line options + for server processes can be specified directly on the + <command>postgres</command> command line + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term><option>-p <replaceable class="parameter">port</replaceable></option></term> + <listitem> + <para> + Specifies the TCP/IP port or local Unix domain socket file + extension on which <command>postgres</command> + is to listen for connections from client 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 during compilation (normally + 5432). If you specify a port other than the default port, + then all client applications must specify the same port using + either command-line options or <envar>PGPORT</envar>. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term><option>-s</option></term> + <listitem> + <para> + Print time information and other statistics at the end of each command. + This is useful for benchmarking or for use in tuning the number of + buffers. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term><option>-S</option></term> + <listitem> + <para> + Specifies that the <command>postgres</command> + process should start up in silent mode. That is, it will + disassociate from the user's (controlling) terminal, start its + own process group, and redirect its standard output and + standard error to <filename>/dev/null</filename>. + </para> + <para> + Using this switch discards all logging output, which is + probably not what you want, since it makes it very difficult + to troubleshoot problems. See below for a better way to start + <command>postgres</command> in the background. + </para> + <para> + <option>--silent-mode=false</option> has the opposite effect + of this option. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term><option>--<replaceable>name</replaceable>=<replaceable>value</replaceable></option></term> + <listitem> + <para> + Sets a named run-time parameter; a shorter form of + <option>-c</>. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term><option>--describe-config</option></term> + <listitem> + <para> + This option dumps out the server's internal configuration variables, + descriptions, and defaults in tab-delimited <command>COPY</> format. + It is designed primarily for use by administration tools. </para> </listitem> </varlistentry> @@ -158,46 +371,199 @@ PostgreSQL documentation <title>Semi-internal Options</title> <para> - The options <option>-f</option>, <option>-O</option>, - <option>-P</option>, <option>-t</option>, and <option>-W</option> - have the same meanings as with the <xref - linkend="app-postmaster"> and are reserved for debugging and - disaster recovery. Further options for internal use are: + There are several other options that may be specified, used + mainly for debugging purposes and in some cases to assist with + recovery of severely damaged databases. There should be no reason + to use them in a production database setup. These are listed + here only for the use by <productname>PostgreSQL</productname> + system developers. Furthermore, any of these options may + disappear or change in a future release without notice. + </para> <variablelist> <varlistentry> + <term><option>-f</option> <literal>{ s | i | m | n | h }</literal></term> + <listitem> + <para> + Forbids the use of particular scan and join methods: + <literal>s</literal> and <literal>i</literal> + disable sequential and index scans respectively, while + <literal>n</literal>, <literal>m</literal>, and <literal>h</literal> + disable nested-loop, merge and hash joins respectively. + </para> + + <para> + Neither sequential scans nor nested-loop joins can be disabled + completely; the <literal>-fs</literal> and + <literal>-fn</literal> options simply discourage the optimizer + from using those plan types if it has any other alternative. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term><option>-n</option></term> + <listitem> + <para> + This option is for debugging problems that cause a server + process to die abnormally. The ordinary strategy in this + situation is to notify all other server processes that they + must terminate and then reinitialize the shared memory and + semaphores. This is because an errant server process could + have corrupted some shared state before terminating. This + option specifies that <command>postgres</command> will + not reinitialize shared data structures. A knowledgeable + system programmer can then use a debugger to examine shared + memory and semaphore state. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term><option>-O</option></term> + <listitem> + <para> + Allows the structure of system tables to be modified. This is + used by <command>initdb</command>. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term><option>-P</option></term> + <listitem> + <para> + Ignore system indexes when reading system tables (but still update + the indexes when modifying the tables). This is useful when + recovering from damaged system indexes. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term><option>-t</option> <literal>pa[rser] | pl[anner] | e[xecutor]</literal></term> + <listitem> + <para> + Print timing statistics for each query relating to each of the + major system modules. This option cannot be used together + with the <option>-s</option> option. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term><option>-T</option></term> + <listitem> + <para> + This option is for debugging problems that cause a server + process to die abnormally. The ordinary strategy in this + situation is to notify all other server processes that they + must terminate and then reinitialize the shared memory and + semaphores. This is because an errant server process could + have corrupted some shared state before terminating. This + option specifies that <command>postgres</command> will + stop all other server 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 server processes by hand. + </para> + </listitem> + </varlistentry> + + <varlistentry> <term><option>-v</option> <replaceable class="parameter">protocol</replaceable></term> <listitem> <para> Specifies the version number of the frontend/backend protocol - to be used for this particular session. + to be used for a particular session. This option is for + internal use only. </para> </listitem> </varlistentry> <varlistentry> - <term><option>-y</option> <replaceable class="parameter">database</replaceable></term> + <term><option>-W</option> <replaceable class="parameter">seconds</replaceable></term> <listitem> <para> - Indicates that this process has been started by a - <command>postmaster</command> and specifies the database to use. - etc. + A delay of this many seconds occurs when a new server process + is started, after it conducts the authentication procedure. + This is intended to give an opportunity to attach to the + server process with a debugger. </para> </listitem> </varlistentry> <varlistentry> - <term><option>--describe-config</option></term> + <term><option>-y</option> <replaceable class="parameter">database</replaceable></term> <listitem> <para> - This option dumps out the server's internal configuration variables, - descriptions, and defaults in tab-delimited <command>COPY</> format. - It is designed primarily for use by administration tools. + Indicates that this is a subprocess started by + <command>postgres</command> and specifies the database to + use. This option is for internal use only. </para> </listitem> </varlistentry> </variablelist> + </refsect2> + + <refsect2> + <title>Options for single-user mode</title> + + <para> + The following options only apply to the single-user mode. </para> + + <variablelist> + <varlistentry> + <term><option>--single</option></term> + <listitem> + <para> + Selects the single-user mode. This must be the first argument + on the command line. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term><replaceable class="parameter">database</replaceable></term> + <listitem> + <para> + Specifies the name of the database to be accessed. If it is + omitted it defaults to the user name. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term><option>-E</option></term> + <listitem> + <para> + Echo all commands. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term><option>-j</option></term> + <listitem> + <para> + Disables use of newline as a statement delimiter. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term><option>-r</option> <replaceable class="parameter">filename</replaceable></term> + <listitem> + <para> + Send all server log output to <replaceable + class="parameter">filename</replaceable>. In normal multiuser + mode, this option is ignored, and <systemitem>stderr</> is + used by all processes. + </para> + </listitem> + </varlistentry> + </variablelist> </refsect2> </refsect1> @@ -206,6 +572,18 @@ PostgreSQL documentation <variablelist> <varlistentry> + <term><envar>PGCLIENTENCODING</envar></term> + + <listitem> + <para> + Default character encoding used by clients. (The clients may + override this individually.) This value can also be set in the + configuration file. + </para> + </listitem> + </varlistentry> + + <varlistentry> <term><envar>PGDATA</envar></term> <listitem> @@ -214,47 +592,154 @@ PostgreSQL documentation </para> </listitem> </varlistentry> + + <varlistentry> + <term><envar>PGDATESTYLE</envar></term> + + <listitem> + <para> + Default value of the <xref linkend="guc-datestyle"> run-time + parameter. (The use of this environment variable is deprecated.) + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term><envar>PGPORT</envar></term> + + <listitem> + <para> + Default port (preferably set in the configuration file) + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term><envar>TZ</envar></term> + + <listitem> + <para> + Server time zone + </para> + </listitem> + </varlistentry> + </variablelist> </refsect1> <refsect1> + <title>Diagnostics</title> + + <para> + A failure message mentioning <literal>semget</> or + <literal>shmget</> probably indicates you need to configure your + kernel to provide adequate shared memory and semaphores. For more + discussion see <xref linkend="kernel-resources">. You may be able + to postpone reconfiguring your kernel by decreasing <xref + linkend="guc-shared-buffers"> to reduce the shared memory + consumption of <productname>PostgreSQL</>, and/or by reducing + <xref linkend="guc-max-connections"> to reduce the semaphore + consumption. + </para> + + <para> + A failure message suggesting that another server is already running + should be checked carefully, for example by using the command +<screen> +<prompt>$</prompt> <userinput>ps ax | grep postgres</userinput> +</screen> + or +<screen> +<prompt>$</prompt> <userinput>ps -ef | grep postgres</userinput> +</screen> + depending on your system. If you are certain that no conflicting + server is running, you may remove the lock file mentioned in the + message and try again. + </para> + + <para> + A failure message indicating inability to bind to a port may + indicate that that port is already in use by some + non-<productname>PostgreSQL</productname> process. You may also + get this error if you terminate <command>postgres</command> + 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 <quote>trusted</quote> and only permit + the Unix superuser to access them. + </para> + + </refsect1> + + <refsect1> <title>Notes</title> + + <para> + If at all possible, <emphasis>do not</emphasis> use + <literal>SIGKILL</literal> to kill the main + <command>postgres</command> server. Doing so will prevent + <command>postgres</command> from freeing the system + resources (e.g., shared memory and semaphores) that it holds before + terminating. This may cause problems for starting a fresh + <command>postgres</command> run. + </para> <para> - To cancel a running query, send the <literal>SIGINT</literal> signal - to the <command>postgres</command> process running that command. + To terminate the <command>postgres</command> server normally, the + signals <literal>SIGTERM</literal>, <literal>SIGINT</literal>, or + <literal>SIGQUIT</literal> can be used. The first will wait for + all clients to terminate before quitting, the second will + forcefully disconnect all clients, and the third will quit + immediately without proper shutdown, resulting in a recovery run + during restart. The <literal>SIGHUP</literal> signal will reload + the server configuration files. It is also possible to send + <literal>SIGHUP</literal> to an individual server process, but that + is usually not sensible. + </para> + + <para> + The utility command <xref linkend="app-pg-ctl"> can be used to + start and shut down the <command>postgres</command> server + safely and comfortably. </para> <para> - To tell <command>postgres</command> to reload the configuration files, - send a <literal>SIGHUP</literal> signal. Normally it's best to - <literal>SIGHUP</literal> the <command>postmaster</command> instead; - the <command>postmaster</command> will in turn <literal>SIGHUP</literal> - each of its children. But in some cases it might be desirable to have only - one <command>postgres</command> process reload the configuration files. + To cancel a running query, send the <literal>SIGINT</literal> signal + to the process running that command. </para> <para> - The <command>postmaster</command> uses <literal>SIGTERM</literal> - to tell a <command>postgres</command> process to quit normally and + The <command>postgres</command> server uses <literal>SIGTERM</literal> + to tell subordinate server processes to quit normally and <literal>SIGQUIT</literal> to terminate without the normal cleanup. - These signals <emphasis>should not</emphasis> be used by users. It is also - unwise to send <literal>SIGKILL</literal> to a <command>postgres</command> - process — the <command>postmaster</command> will interpret this as - a crash in <command>postgres</command>, and will force all the sibling - <command>postgres</command> processes to quit as part of its standard - crash-recovery procedure. + These signals <emphasis>should not</emphasis> be used by users. It + is also unwise to send <literal>SIGKILL</literal> to a server + process — the main <command>postgres</command> process will + interpret this as a crash and will force all the sibling processes + to quit as part of its standard crash-recovery procedure. </para> + </refsect1> + <refsect1 id="app-postgres-bugs"> + <title>Bugs</title> + <para> + The <option>--</> options will not work on <systemitem + class="osname">FreeBSD</> or <systemitem class="osname">OpenBSD</>. + Use <option>-c</> instead. This is a bug in the affected operating + systems; a future release of <productname>PostgreSQL</productname> + will provide a workaround if this is not fixed. + </para> </refsect1> <refsect1> <title>Usage</title> <para> - Start a stand-alone server with a command like + To start a single-user mode server, use a command like <screen> -<userinput>postgres -D /usr/local/pgsql/data <replaceable>other-options</> my_database</userinput> +<userinput>postgres --single -D /usr/local/pgsql/data <replaceable>other-options</> my_database</userinput> </screen> Provide the correct path to the database directory with <option>-D</>, or make sure that the environment variable <envar>PGDATA</> is set. @@ -262,7 +747,7 @@ PostgreSQL documentation </para> <para> - Normally, the stand-alone server treats newline as the command + Normally, the single-user mode server treats newline as the command entry terminator; there is no intelligence about semicolons, as there is in <application>psql</>. To continue a command across multiple lines, you must type backslash just before each @@ -285,10 +770,57 @@ PostgreSQL documentation </para> <para> - Note that the stand-alone server does not provide sophisticated + Note that the single-user mode server does not provide sophisticated line-editing features (no command history, for example). </para> + </refsect1> + + <refsect1 id="app-postgres-examples"> + <title>Examples</title> + <para> + To start <command>postgres</command> in the background + using default values, type: + +<screen> +<prompt>$</prompt> <userinput>nohup postgres >logfile 2>&1 </dev/null &</userinput> +</screen> + </para> + + <para> + To start <command>postgres</command> with a specific + port: +<screen> +<prompt>$</prompt> <userinput>postgres -p 1234</userinput> +</screen> + This command will start up <command>postgres</command> + communicating through the port 1234. In order to connect to this + <command>postgres</command> using <application>psql</>, you would need to + run it as +<screen> +<prompt>$</prompt> <userinput>psql -p 1234</userinput> +</screen> + or set the environment variable <envar>PGPORT</envar>: +<screen> +<prompt>$</prompt> <userinput>export PGPORT=1234</userinput> +<prompt>$</prompt> <userinput>psql</userinput> +</screen> + </para> + + <para> + Named run-time parameters can be set in either of these styles: +<screen> +<prompt>$</prompt> <userinput>postgres -c work_mem=1234</userinput> +<prompt>$</prompt> <userinput>postgres --work-mem=1234</userinput> +</screen> + Either form overrides whatever setting might exist for + <varname>work_mem</> in <filename>postgresql.conf</>. Notice that + underscores in parameter names can be written as either underscore + or dash on the command line. Except for short-term experiments, + it's probably better practice to edit the setting in + <filename>postgresql.conf</> than to rely on a command-line switch + to set a parameter. + </para> </refsect1> <refsect1> @@ -296,26 +828,7 @@ PostgreSQL documentation <para> <xref linkend="app-initdb">, - <xref linkend="app-ipcclean">, - <xref linkend="app-postmaster"> + <xref linkend="app-pg-ctl"> </para> </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: ---> diff --git a/doc/src/sgml/ref/postmaster.sgml b/doc/src/sgml/ref/postmaster.sgml index 94c965a9d2..49a5278fb3 100644 --- a/doc/src/sgml/ref/postmaster.sgml +++ b/doc/src/sgml/ref/postmaster.sgml @@ -1,5 +1,5 @@ <!-- -$PostgreSQL: pgsql/doc/src/sgml/ref/postmaster.sgml,v 1.56 2006/01/06 01:35:09 tgl Exp $ +$PostgreSQL: pgsql/doc/src/sgml/ref/postmaster.sgml,v 1.57 2006/06/18 15:38:36 petere Exp $ PostgreSQL documentation --> @@ -12,7 +12,7 @@ PostgreSQL documentation <refnamediv> <refname id="postmaster-ref">postmaster</refname> - <refpurpose><productname>PostgreSQL</productname> multiuser database server</refpurpose> + <refpurpose><productname>PostgreSQL</productname> database server</refpurpose> </refnamediv> <indexterm zone="app-postmaster"> @@ -30,659 +30,15 @@ PostgreSQL documentation <title>Description</title> <para> - <command>postmaster</command> is the - <productname>PostgreSQL</productname> multiuser database server. - In order for a client application to access a database it connects - (over a network or locally) to a running - <command>postmaster</command>. The - <command>postmaster</command> then starts a separate server - process (<quote><xref linkend="app-postgres"></quote>) to handle - the connection. The <command>postmaster</command> also - manages the communication among server processes. + <command>postmaster</command> is a deprecated alias of <command>postgres</command>. </para> - - <para> - By default the <command>postmaster</command> starts in the - foreground and prints log messages to the standard error stream. In - practical applications the <command>postmaster</command> - should be started as a background process, perhaps at boot time. - </para> - - <para> - One <command>postmaster</command> always manages the data - from exactly one database cluster. A database cluster is a - collection of databases that is stored at a common file system - location (the <quote>data area</quote>). - More than one <command>postmaster</command> process can run on a system - at one time, so long as they use different data areas and different - communication ports (see below). - </para> - - <para> - When the <command>postmaster</command> starts it needs - to know the location of the data area. - The location must be specified by the <option>-D</option> option - or the <envar>PGDATA</envar> environment variable; there is no default. - Typically, <option>-D</option> or <envar>PGDATA</envar> points - directly to the data area directory created by <application>initdb</>. - Other possible file layouts are discussed in - <xref linkend="runtime-config-file-locations">. - A data area is created with <xref linkend="app-initdb">. - </para> - </refsect1> - - <refsect1 id="app-postmaster-options"> - <title>Options</title> - - <para> - <command>postmaster</command> accepts the following - command line arguments. For a detailed discussion of the options - consult <xref linkend="runtime-config">. You can save typing most of these - options by setting up a configuration file. - </para> - - <refsect2> - <title>General Purpose</title> - - <variablelist> - <varlistentry> - <term><option>-A 0|1</option></term> - <listitem> - <para> - Enables run-time assertion checks, which is a debugging aid to - detect programming mistakes. This option is only available if - assertions were enabled when <productname>PostgreSQL</> was - compiled. If so, the default is on. - </para> - </listitem> - </varlistentry> - - <varlistentry> - <term><option>-B <replaceable class="parameter">nbuffers</replaceable></option></term> - <listitem> - <para> - Sets the number of shared buffers for use by the server - processes. The default value of this parameter is chosen - automatically by <application>initdb</application>; refer to <xref - linkend="runtime-config-resource-memory"> for more information. - </para> - </listitem> - </varlistentry> - - <varlistentry> - <term><option>-c <replaceable>name</replaceable>=<replaceable>value</replaceable></option></term> - <listitem> - <para> - Sets a named run-time parameter. The configuration parameters - supported by <productname>PostgreSQL</productname> are - described in <xref linkend="runtime-config">. Most of the - other command line options are in fact short forms of such a - parameter assignment. <option>-c</> can appear multiple times - to set multiple parameters. - </para> - </listitem> - </varlistentry> - - <varlistentry> - <term><option>-d <replaceable>debug-level</replaceable></option></term> - <listitem> - <para> - Sets the debug level. The higher this value is set, the more - debugging output is written to the server log. Values are from - 1 to 5. - </para> - </listitem> - </varlistentry> - - <varlistentry> - <term><option>-D <replaceable class="parameter">datadir</replaceable></option></term> - <listitem> - <para> - Specifies the file system location of the data directory or - configuration file(s). See - <xref linkend="runtime-config-file-locations"> for details. - </para> - </listitem> - </varlistentry> - - <varlistentry> - <term><option>-e</option></term> - <listitem> - <para> - Sets the default date style to <quote>European</quote>, that is - <literal>DMY</> ordering of input date fields. This also causes - the day to be printed before the month in certain date output formats. - See <xref linkend="datatype-datetime"> for more information. - </para> - </listitem> - </varlistentry> - - <varlistentry> - <term><option>-F</option></term> - <listitem> - <para> - Disables <function>fsync</function> calls for improved - performance, at the risk of data corruption in the event of a - system crash. Specifying this option is equivalent to - disabling the <xref linkend="guc-fsync"> configuration - parameter. Read the detailed documentation before using this! - </para> - - <para> - <option>--fsync=true</option> has the opposite effect - of this option. - </para> - </listitem> - </varlistentry> - - <varlistentry> - <term><option>-h <replaceable class="parameter">hostname</replaceable></option></term> - <listitem> - <para> - Specifies the IP host name or address on which the - <command>postmaster</command> is to listen for TCP/IP - connections from client applications. The value can also be a - comma-separated list of addresses, or <literal>*</> to specify - listening on all available interfaces. An empty value - specifies not listening on any IP addresses, in which case - only Unix-domain sockets can be used to connect to the - <command>postmaster</command>. Defaults to listening only on - <systemitem class="systemname">localhost</systemitem>. - Specifying this option is equivalent to setting the <xref - linkend="guc-listen-addresses"> configuration parameter. - </para> - </listitem> - </varlistentry> - - <varlistentry> - <term><option>-i</option></term> - <listitem> - <para> - Allows remote clients to connect via TCP/IP (Internet domain) - connections. Without this option, only local connections are - accepted. This option is equivalent to setting - <varname>listen_addresses</> to <literal>*</> in - <filename>postgresql.conf</> or via <option>-h</>. - </para> - <para> - This option is deprecated since it does not allow access to the - full functionality of <xref linkend="guc-listen-addresses">. - It's usually better to set <varname>listen_addresses</> directly. - </para> - </listitem> - </varlistentry> - - <varlistentry> - <term><option>-k <replaceable class="parameter">directory</replaceable></option></term> - <listitem> - <para> - Specifies the directory of the Unix-domain socket on which the - <command>postmaster</command> is to listen for - connections from client applications. The default is normally - <filename>/tmp</filename>, but can be changed at build time. - </para> - </listitem> - </varlistentry> - - <varlistentry> - <term><option>-l</option></term> - <listitem> - <para> - Enables secure connections using <acronym>SSL</acronym>. - <productname>PostgreSQL</productname> must have been compiled with - support for <acronym>SSL</acronym> for this option to be - available. For more information on using <acronym>SSL</acronym>, - refer to <xref linkend="ssl-tcp">. - </para> - </listitem> - </varlistentry> - - <varlistentry> - <term><option>-N <replaceable class="parameter">max-connections</replaceable></option></term> - <listitem> - <para> - Sets the maximum number of client connections that this - <command>postmaster</command> will accept. By - default, this value is 32, but it can be set as high as your - system will support. (Note that - <option>-B</option> is required to be at least twice - <option>-N</option>. See <xref linkend="kernel-resources"> for a discussion of - system resource requirements for large numbers of client - connections.) Specifying this option is equivalent to setting the - <xref linkend="guc-max-connections"> configuration parameter. - </para> - </listitem> - </varlistentry> - - <varlistentry> - <term><option>-o <replaceable class="parameter">extra-options</replaceable></option></term> - <listitem> - <para> - The command line-style options specified in <replaceable - class="parameter">extra-options</replaceable> are passed to - all server processes started by this - <command>postmaster</command>. See <xref - linkend="app-postgres"> for possibilities. If the option - string contains any spaces, the entire string must be quoted. - </para> - - <para> - The use of this option is obsolete; all command-line options - for server processes can be specified directly on the - <command>postmaster</command> command line - </para> - </listitem> - </varlistentry> - - <varlistentry> - <term><option>-p <replaceable class="parameter">port</replaceable></option></term> - <listitem> - <para> - Specifies the TCP/IP port or local Unix domain socket file - extension on which the <command>postmaster</command> - is to listen for connections from client 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 during compilation (normally - 5432). If you specify a port other than the default port, - then all client applications must specify the same port using - either command-line options or <envar>PGPORT</envar>. - </para> - </listitem> - </varlistentry> - - <varlistentry> - <term><option>-s</option></term> - <listitem> - <para> - Print time information and other statistics at the end of each command. - This is useful for benchmarking or for use in tuning the number of - buffers. - </para> - </listitem> - </varlistentry> - - <varlistentry> - <term><option>-S</option></term> - <listitem> - <para> - Specifies that the <command>postmaster</command> - process should start up in silent mode. That is, it will - disassociate from the user's (controlling) terminal, start its - own process group, and redirect its standard output and - standard error to <filename>/dev/null</filename>. - </para> - <para> - Using this switch discards all logging output, which is - probably not what you want, since it makes it very difficult - to troubleshoot problems. See below for a better way to start - the <command>postmaster</command> in the background. - </para> - <para> - <option>--silent-mode=false</option> has the opposite effect - of this option. - </para> - </listitem> - </varlistentry> - - <varlistentry> - <term><option>--<replaceable>name</replaceable>=<replaceable>value</replaceable></option></term> - <listitem> - <para> - Sets a named run-time parameter; a shorter form of - <option>-c</>. - </para> - </listitem> - </varlistentry> - - </variablelist> - </refsect2> - - <refsect2> - <title>Semi-internal Options</title> - - <para> - There are several other options that may be specified, used - mainly for debugging purposes and in some cases to assist with - recovery of severely damaged databases. There should be no reason - to use them in a production database setup. These are listed - here only for the use by <productname>PostgreSQL</productname> - system developers. <emphasis>Use of any of these options is - highly discouraged.</emphasis> Furthermore, any of these options - may disappear or change in a future release without notice. - </para> - - <variablelist> - <varlistentry> - <term><option>-f</option> <literal>{ s | i | m | n | h }</literal></term> - <listitem> - <para> - Forbids the use of particular scan and join methods: - <literal>s</literal> and <literal>i</literal> - disable sequential and index scans respectively, while - <literal>n</literal>, <literal>m</literal>, and <literal>h</literal> - disable nested-loop, merge and hash joins respectively. - </para> - - <para> - Neither sequential scans nor nested-loop joins can be disabled - completely; the <literal>-fs</literal> and - <literal>-fn</literal> options simply discourage the optimizer - from using those plan types if it has any other alternative. - </para> - </listitem> - </varlistentry> - - <varlistentry> - <term><option>-n</option></term> - <listitem> - <para> - This option is for debugging problems that cause a server - process to die abnormally. The ordinary strategy in this - situation is to notify all other server processes that they - must terminate and then reinitialize the shared memory and - semaphores. This is because an errant server process could - have corrupted some shared state before terminating. This - option specifies that the <command>postmaster</command> will - not reinitialize shared data structures. A knowledgeable - system programmer can then use a debugger to examine shared - memory and semaphore state. - </para> - </listitem> - </varlistentry> - - <varlistentry> - <term><option>-O</option></term> - <listitem> - <para> - Allows the structure of system tables to be modified. This is - used by <command>initdb</command>. - </para> - </listitem> - </varlistentry> - - <varlistentry> - <term><option>-P</option></term> - <listitem> - <para> - Ignore system indexes when reading system tables (but still update - the indexes when modifying the tables). This is useful when - recovering from damaged system indexes. - </para> - </listitem> - </varlistentry> - - <varlistentry> - <term><option>-t</option> <literal>pa[rser] | pl[anner] | e[xecutor]</literal></term> - <listitem> - <para> - Print timing statistics for each query relating to each of the - major system modules. This option cannot be used together - with the <option>-s</option> option. - </para> - </listitem> - </varlistentry> - - <varlistentry> - <term><option>-T</option></term> - <listitem> - <para> - This option is for debugging problems that cause a server - process to die abnormally. The ordinary strategy in this - situation is to notify all other server processes that they - must terminate and then reinitialize the shared memory and - semaphores. This is because an errant server process could - have corrupted some shared state before terminating. This - option specifies that the <command>postmaster</command> will - stop all other server 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 server processes by hand. - </para> - </listitem> - </varlistentry> - - <varlistentry> - <term><option>-W</option> <replaceable class="parameter">seconds</replaceable></term> - <listitem> - <para> - A delay of this many seconds occurs when a new server process - is started, after it conducts the authentication procedure. - This is intended to give an opportunity to attach to the - server process with a debugger. - </para> - </listitem> - </varlistentry> - </variablelist> - </refsect2> - </refsect1> - - <refsect1> - <title>Environment</title> - - <variablelist> - <varlistentry> - <term><envar>PGCLIENTENCODING</envar></term> - - <listitem> - <para> - Default character encoding used by clients. (The clients may - override this individually.) This value can also be set in the - configuration file. - </para> - </listitem> - </varlistentry> - - <varlistentry> - <term><envar>PGDATA</envar></term> - - <listitem> - <para> - Default data directory location - </para> - </listitem> - </varlistentry> - - <varlistentry> - <term><envar>PGDATESTYLE</envar></term> - - <listitem> - <para> - Default value of the <xref linkend="guc-datestyle"> run-time - parameter. (The use of this environment variable is deprecated.) - </para> - </listitem> - </varlistentry> - - <varlistentry> - <term><envar>PGPORT</envar></term> - - <listitem> - <para> - Default port (preferably set in the configuration file) - </para> - </listitem> - </varlistentry> - - <varlistentry> - <term><envar>TZ</envar></term> - - <listitem> - <para> - Server time zone - </para> - </listitem> - </varlistentry> - - </variablelist> - </refsect1> - - <refsect1> - <title>Diagnostics</title> - - <para> - A failure message mentioning <literal>semget</> or <literal>shmget</> - probably indicates you need to configure your kernel to provide adequate - shared memory and semaphores. For more discussion see <xref - linkend="kernel-resources">. - </para> - - <tip> - <para> - You may be able to postpone reconfiguring your kernel by - decreasing <xref linkend="guc-shared-buffers"> to reduce the - shared memory consumption of <productname>PostgreSQL</>, and/or - by reducing <xref linkend="guc-max-connections"> to reduce the - semaphore consumption. - </para> - </tip> - - <para> - A failure message suggesting that another postmaster is already running - should be checked carefully, for example by using the command -<screen> -<prompt>$</prompt> <userinput>ps ax | grep postmaster</userinput> -</screen> - or -<screen> -<prompt>$</prompt> <userinput>ps -ef | grep postmaster</userinput> -</screen> - depending on your system. If you are certain that no conflicting - postmaster is running, you may remove the lock file mentioned in the - message and try again. - </para> - - <para> - A failure message indicating inability to bind to a port may - indicate that that port is already in use by some - non-<productname>PostgreSQL</productname> process. You may also - get this error if you terminate the <command>postmaster</command> - 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 <quote>trusted</quote> and only permit - the Unix superuser to access them. - </para> - - </refsect1> - - <refsect1> - <title>Notes</title> - - <para> - If at all possible, <emphasis>do not</emphasis> use - <literal>SIGKILL</literal> to kill the - <command>postmaster</command>. Doing so will prevent - <command>postmaster</command> from freeing the system - resources (e.g., shared memory and semaphores) that it holds before - terminating. This may cause problems for starting a fresh - <command>postmaster</command> run. - </para> - - <para> - To terminate the <command>postmaster</command> normally, - the signals <literal>SIGTERM</literal>, <literal>SIGINT</literal>, - or <literal>SIGQUIT</literal> can be used. The first will wait for - all clients to terminate before quitting, the second will - forcefully disconnect all clients, and the third will quit - immediately without proper shutdown, resulting in a recovery run - during restart. The <literal>SIGHUP</literal> signal will - reload the server configuration files. - </para> - - <para> - The utility command <xref linkend="app-pg-ctl"> can be used to - start and shut down the <command>postmaster</command> - safely and comfortably. - </para> - - <para> - The <option>--</> options will not work on <systemitem - class="osname">FreeBSD</> or <systemitem class="osname">OpenBSD</>. - Use <option>-c</> instead. This is a bug in the affected operating - systems; a future release of <productname>PostgreSQL</productname> - will provide a workaround if this is not fixed. - </para> - - </refsect1> - - <refsect1 id="app-postmaster-examples"> - <title>Examples</title> - <para> - To start <command>postmaster</command> in the background - using default values, type: - -<screen> -<prompt>$</prompt> <userinput>nohup postmaster >logfile 2>&1 </dev/null &</userinput> -</screen> - </para> - - <para> - To start <command>postmaster</command> with a specific - port: -<screen> -<prompt>$</prompt> <userinput>postmaster -p 1234</userinput> -</screen> - This command will start up <command>postmaster</command> - communicating through the port 1234. In order to connect to this - <command>postmaster</command> using <application>psql</>, you would need to - run it as -<screen> -<prompt>$</prompt> <userinput>psql -p 1234</userinput> -</screen> - or set the environment variable <envar>PGPORT</envar>: -<screen> -<prompt>$</prompt> <userinput>export PGPORT=1234</userinput> -<prompt>$</prompt> <userinput>psql</userinput> -</screen> - </para> - - <para> - Named run-time parameters can be set in either of these styles: -<screen> -<prompt>$</prompt> <userinput>postmaster -c work_mem=1234</userinput> -<prompt>$</prompt> <userinput>postmaster --work-mem=1234</userinput> -</screen> - Either form overrides whatever setting might exist for <varname>work_mem</> - in <filename>postgresql.conf</>. Notice that underscores in parameter - names can be written as either underscore or dash on the command line. - </para> - - <tip> - <para> - Except for short-term experiments, - it's probably better practice to edit the setting in - <filename>postgresql.conf</> than to rely on a command-line switch - to set a parameter. - </para> - </tip> </refsect1> <refsect1> <title>See Also</title> <para> - <xref linkend="app-initdb">, - <xref linkend="app-pg-ctl"> + <xref linkend="app-postgres"> </para> </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: ---> diff --git a/doc/src/sgml/ref/reindex.sgml b/doc/src/sgml/ref/reindex.sgml index 8c07d1caee..d589f9e82a 100644 --- a/doc/src/sgml/ref/reindex.sgml +++ b/doc/src/sgml/ref/reindex.sgml @@ -1,5 +1,5 @@ <!-- -$PostgreSQL: pgsql/doc/src/sgml/ref/reindex.sgml,v 1.29 2005/09/12 16:43:29 tgl Exp $ +$PostgreSQL: pgsql/doc/src/sgml/ref/reindex.sgml,v 1.30 2006/06/18 15:38:36 petere Exp $ PostgreSQL documentation --> @@ -148,7 +148,7 @@ REINDEX { INDEX | TABLE | DATABASE | SYSTEM } <replaceable class="PARAMETER">nam </para> <para> - One way to do this is to shut down the postmaster and start a stand-alone + One way to do this is to shut down the server and start a single-user <productname>PostgreSQL</productname> server with the <option>-P</option> option included on its command line. Then, <command>REINDEX DATABASE</>, <command>REINDEX SYSTEM</>, @@ -156,9 +156,9 @@ REINDEX { INDEX | TABLE | DATABASE | SYSTEM } <replaceable class="PARAMETER">nam issued, depending on how much you want to reconstruct. If in doubt, use <command>REINDEX SYSTEM</> to select reconstruction of all system indexes in the database. Then quit - the standalone server session and restart the regular server. + the single-user server session and restart the regular server. See the <xref linkend="app-postgres"> reference page for more - information about how to interact with the stand-alone server + information about how to interact with the single-user server interface. </para> diff --git a/doc/src/sgml/ref/show.sgml b/doc/src/sgml/ref/show.sgml index 843c13756b..f6123ba503 100644 --- a/doc/src/sgml/ref/show.sgml +++ b/doc/src/sgml/ref/show.sgml @@ -1,5 +1,5 @@ <!-- -$PostgreSQL: pgsql/doc/src/sgml/ref/show.sgml,v 1.39 2005/06/14 20:42:52 momjian Exp $ +$PostgreSQL: pgsql/doc/src/sgml/ref/show.sgml,v 1.40 2006/06/18 15:38:36 petere Exp $ PostgreSQL documentation --> @@ -36,7 +36,7 @@ SHOW ALL the <envar>PGOPTIONS</envar> environmental variable (when using <application>libpq</> or a <application>libpq</>-based application), or through command-line flags when starting the - <command>postmaster</command>. See <xref + <command>postgres</command>. See <xref linkend="runtime-config"> for details. </para> </refsect1> |