diff options
| -rw-r--r-- | doc/src/sgml/monitoring.sgml | 43 | ||||
| -rw-r--r-- | doc/src/sgml/plpgsql.sgml | 5 | ||||
| -rw-r--r-- | doc/src/sgml/runtime.sgml | 123 |
3 files changed, 107 insertions, 64 deletions
diff --git a/doc/src/sgml/monitoring.sgml b/doc/src/sgml/monitoring.sgml index 3d120409b10..4486745c760 100644 --- a/doc/src/sgml/monitoring.sgml +++ b/doc/src/sgml/monitoring.sgml @@ -1,5 +1,5 @@ <!-- -$PostgreSQL: pgsql/doc/src/sgml/monitoring.sgml,v 1.25 2003/11/29 19:51:37 pgsql Exp $ +$PostgreSQL: pgsql/doc/src/sgml/monitoring.sgml,v 1.26 2004/03/26 03:18:28 neilc Exp $ --> <chapter id="monitoring"> @@ -28,7 +28,8 @@ $PostgreSQL: pgsql/doc/src/sgml/monitoring.sgml,v 1.25 2003/11/29 19:51:37 pgsql but one should not neglect regular Unix monitoring programs such as <command>ps</> and <command>top</>. Also, once one has identified a poorly-performing query, further investigation may be needed using - <productname>PostgreSQL</productname>'s <command>EXPLAIN</> command. + <productname>PostgreSQL</productname>'s <xref linkend="sql-explain" + endterm="sql-explain-title"> command. <xref linkend="using-explain"> discusses <command>EXPLAIN</> and other methods for understanding the behavior of an individual query. @@ -126,28 +127,30 @@ postgres: <replaceable>user</> <replaceable>database</> <replaceable>host</> <re </para> <para> - The parameter <varname>stats_start_collector</varname> must be set to - <literal>true</> for the statistics collector to - be launched at all. This is the default and recommended setting, - but it may be turned off if you have no interest in statistics and - want to squeeze out every last drop of overhead. (The savings is - likely to be small, however.) Note that this option - cannot be changed while the server is running. + The parameter <xref linkend="guc-stats-start-collector"> must be + set to <literal>true</> for the statistics collector to be launched + at all. This is the default and recommended setting, but it may be + turned off if you have no interest in statistics and want to + squeeze out every last drop of overhead. (The savings is likely to + be small, however.) Note that this option cannot be changed while + the server is running. </para> <para> - The parameters <varname>stats_command_string</varname>, - <varname>stats_block_level</varname>, - and <varname>stats_row_level</varname> control how much information is + The parameters <xref linkend="guc-stats-command-string">, + <xref linkend="guc-stats-block-level">, and <xref + linkend="guc-stats-row-level"> control how much information is actually sent to the collector and thus determine how much run-time - overhead occurs. These respectively determine whether a server process - sends its current command string, disk-block-level access statistics, and - row-level access statistics to the collector. Normally these parameters are - set in <filename>postgresql.conf</> so that they apply to all server - processes, but it is possible to turn them on or off in individual sessions - using the <command>SET</> command. (To prevent ordinary users - from hiding their activity from the administrator, only superusers are - allowed to change these parameters with <command>SET</>.) + overhead occurs. These respectively determine whether a server + process sends its current command string, disk-block-level access + statistics, and row-level access statistics to the collector. + Normally these parameters are set in <filename>postgresql.conf</> + so that they apply to all server processes, but it is possible to + turn them on or off in individual sessions using the <xref + linkend="sql-set" endterm="sql-set-title"> command. (To prevent + ordinary users from hiding their activity from the administrator, + only superusers are allowed to change these parameters with + <command>SET</>.) </para> <note> diff --git a/doc/src/sgml/plpgsql.sgml b/doc/src/sgml/plpgsql.sgml index c84967f3266..af521f30729 100644 --- a/doc/src/sgml/plpgsql.sgml +++ b/doc/src/sgml/plpgsql.sgml @@ -1,5 +1,5 @@ <!-- -$PostgreSQL: pgsql/doc/src/sgml/plpgsql.sgml,v 1.36 2004/02/27 03:59:23 neilc Exp $ +$PostgreSQL: pgsql/doc/src/sgml/plpgsql.sgml,v 1.37 2004/03/26 03:18:28 neilc Exp $ --> <chapter id="plpgsql"> @@ -128,7 +128,8 @@ END; <para> The <application>PL/pgSQL</application> <command>EXECUTE</command> statement is not related to the - <command>EXECUTE</command> statement supported by the + <xref linkend="sql-execute" endterm="sql-execute-title"> SQL + statement supported by the <productname>PostgreSQL</productname> server. The server's <command>EXECUTE</command> statement cannot be used within <application>PL/pgSQL</> functions (and is not needed). diff --git a/doc/src/sgml/runtime.sgml b/doc/src/sgml/runtime.sgml index 93902043e35..73bd7fd8352 100644 --- a/doc/src/sgml/runtime.sgml +++ b/doc/src/sgml/runtime.sgml @@ -1,5 +1,5 @@ <!-- -$PostgreSQL: pgsql/doc/src/sgml/runtime.sgml,v 1.254 2004/03/24 22:40:28 tgl Exp $ +$PostgreSQL: pgsql/doc/src/sgml/runtime.sgml,v 1.255 2004/03/26 03:18:28 neilc Exp $ --> <Chapter Id="runtime"> @@ -521,12 +521,14 @@ env PGOPTIONS='-c geqo=off' psql Furthermore, it is possible to assign a set of option settings to a user or a database. Whenever a session is started, the default settings for the user and database involved are loaded. The - commands <command>ALTER DATABASE</command> and <command>ALTER - USER</command>, respectively, are used to configure these - settings. Per-database settings override anything received - from the <command>postmaster</command> command-line or the - configuration file, and in turn are overridden by per-user - settings; both are overridden by per-session options. + commands <xref linkend="sql-alterdatabase" + endterm="sql-alterdatabase-title"> and <xref + linkend="sql-alteruser" endterm="sql-alteruser-title">, + respectively, are used to configure these settings. Per-database + settings override anything received from the + <command>postmaster</command> command-line or the configuration + file, and in turn are overridden by per-user settings; both are + overridden by per-session options. </para> <para> @@ -652,7 +654,7 @@ SET ENABLE_SEQSCAN TO OFF; server is to listen for connections from client applications. The default is normally <filename>/tmp</filename>, but can be changed at build time. - This parameter can only be set at server start. + This parameter can only be set at server start. </para> </listitem> </varlistentry> @@ -711,10 +713,11 @@ SET ENABLE_SEQSCAN TO OFF; <term><varname>rendezvous_name</varname> (<type>string</type>)</term> <listitem> <para> - Specifies the Rendezvous broadcast name. By default, the - computer name is used, specified as an empty string ''. - This option is only meaningful on platforms that support Rendezvous. - This option can only be set at server start. + Specifies the <productname>Rendezvous</productname> broadcast + name. By default, the computer name is used, specified as an + empty string ''. This option is only meaningful on platforms + that support <productname>Rendezvous</productname>. This + option can only be set at server start. </para> </listitem> </varlistentry> @@ -759,10 +762,13 @@ SET ENABLE_SEQSCAN TO OFF; <term><varname>password_encryption</varname> (<type>boolean</type>)</term> <listitem> <para> - When a password is specified in <command>CREATE USER</> or - <command>ALTER USER</> without writing either <literal>ENCRYPTED</> or - <literal>UNENCRYPTED</>, this option determines whether the password is to be - encrypted. The default is on (encrypt the password). + When a password is specified in <xref + linkend="sql-createuser" endterm="sql-createuser-title"> or + <xref linkend="sql-alteruser" endterm="sql-alteruser-title"> + without writing either <literal>ENCRYPTED</> or + <literal>UNENCRYPTED</>, this option determines whether the + password is to be encrypted. The default is on (encrypt the + password). </para> </listitem> </varlistentry> @@ -1010,13 +1016,14 @@ SET ENABLE_SEQSCAN TO OFF; <title>Cost-Based Vacuum Delay</title> <para> - During the execution of <command>VACUUM</command> - and <command>ANALYZE</command> commands, - the system maintains an internal counter that keeps track of the - estimated cost of the various I/O operations that are performed. - When the accumulated cost reaches a limit - (specified by <varname>vacuum_cost_limit</varname>), the process - performing the operation will sleep for a while (specified by + During the execution of <xref linkend="sql-vacuum" + endterm="sql-vacuum-title"> and <xref linkend="sql-analyze" + endterm="sql-analyze-title"> commands, the system maintains an + internal counter that keeps track of the estimated cost of the + various I/O operations that are performed. When the accumulated + cost reaches a limit (specified by + <varname>vacuum_cost_limit</varname>), the process performing + the operation will sleep for a while (specified by <varname>vacuum_cost_naptime</varname>). Then it will reset the counter and continue execution. </para> @@ -1306,10 +1313,13 @@ SET ENABLE_SEQSCAN TO OFF; choose a better plan. Other ways to improve the quality of the plans chosen by the optimizer include configuring the <xref linkend="runtime-config-query-constants" - endterm="runtime-config-query-constants-title">, running - <command>ANALYZE</command> more frequently, and increasing the - amount of statistics collected for a particular column using - <command>ALTER TABLE SET STATISTICS</command>. + endterm="runtime-config-query-constants-title">, running <xref + linkend="sql-analyze" endterm="sql-analyze-title"> more + frequently, increasing the value of the <xref + linkend="guc-default-statistics-target"> configuration parameter, + and increasing the amount of statistics collected for a + particular column using <command>ALTER TABLE SET + STATISTICS</command>. </para> </note> @@ -2115,13 +2125,27 @@ SET ENABLE_SEQSCAN TO OFF; <term><varname>log_statement</varname> (<type>boolean</type>)</term> <listitem> <para> - Causes each SQL statement to be logged. The default is off. - <command>EXECUTE</> only displays the plan name, not the - prepared query. Server-side languages like - <application>PL/pgSQL</> that store functions in a cache only - display their queries on first function call. Only superusers can - turn off this option if it is enabled by the administrator. + Causes each SQL statement to be logged. The default is + off. Only superusers can disable this option if it has been + enabled by an administrator. </para> + + <note> + <para> + When the <command>EXECUTE</command> statement is logged, only + the name of the prepared statement is recorded, not the + entire prepared statement. + </para> + + <para> + When a function is defined in a server-side language like + <application>PL/pgSQL</application>, any queries executed by + the function will only be logged the first time that the + function is invoked in a particular session. This is because + the <application>PL/pgSQL</application> keeps a cache of the + query plans produced for the SQL statements in the function. + </para> + </note> </listitem> </varlistentry> @@ -2202,14 +2226,27 @@ SET ENABLE_SEQSCAN TO OFF; </listitem> </varlistentry> - <varlistentry> + <varlistentry id="guc-stats-block-level" xreflabel="guc_stats_block_level"> <term><varname>stats_block_level</varname> (<type>boolean</type>)</term> + <listitem> + <para> + Enables the collection of block-level statistics on database + activity. This option is disabled by default. If this option + is enabled, the data that is produced can be accessed via the + <structname>pg_stat</structname> and + <structname>pg_statio</structname> family of system views; + refer to <xref linkend="monitoring"> for more information. + </para> + </listitem> + </varlistentry> + + <varlistentry id="guc-stats-row-level" xreflabel="guc_stats_row_level"> <term><varname>stats_row_level</varname> (<type>boolean</type>)</term> <listitem> <para> - These enable the collection of block-level and row-level statistics - on database activity, respectively. These options are off by - default. This data can be accessed via the + Enables the collection of row-level statistics on database + activity. This option is disabled by default. If this option + is enabled, the data that is produced can be accessed via the <structname>pg_stat</structname> and <structname>pg_statio</structname> family of system views; refer to <xref linkend="monitoring"> for more information. @@ -2311,10 +2348,12 @@ SET ENABLE_SEQSCAN TO OFF; <term><varname>check_function_bodies</varname> (<type>boolean</type>)</term> <listitem> <para> - This parameter is normally true. When set false, it disables - validation of the function body string in <command>CREATE FUNCTION</>. - Disabling validation is occasionally useful to avoid problems such as - forward references when restoring function definitions from a dump. + This parameter is normally true. When set to false, it disables + validation of the function body string in <xref + linkend="sql-createfunction" + endterm="sql-createfunction-title">. Disabling validation is + occasionally useful to avoid problems such as forward + references when restoring function definitions from a dump. </para> </listitem> </varlistentry> @@ -2503,7 +2542,7 @@ SET ENABLE_SEQSCAN TO OFF; <listitem> <para> Sets the locale to use for formatting numbers, for example - with the <function>to_char()</function> family of + with the <function>to_char</function> family of functions. Acceptable values are system-dependent; see <xref linkend="locale"> for more information. If this variable is set to the empty string (which is the default) then the value |