8000 More cross-reference work, other minor SGML fixes and improvements. · postgrespro/postgres_cluster@1090aa8 · GitHub
[go: up one dir, main page]
Skip to content

Commit 1090aa8

Browse files
author
Neil Conway
committed
More cross-reference work, other minor SGML fixes and improvements.
1 parent fda3449 commit 1090aa8

File tree

3 files changed

+107
-64
lines changed

3 files changed

+107
-64
lines changed

‎doc/src/sgml/monitoring.sgml

Lines changed: 23 additions & 20 deletions
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,5 @@
11
<!--
2-
$PostgreSQL: pgsql/doc/src/sgml/monitoring.sgml,v 1.25 2003/11/29 19:51:37 pgsql Exp $
2+
$PostgreSQL: pgsql/doc/src/sgml/monitoring.sgml,v 1.26 2004/03/26 03:18:28 neilc Exp $
33
-->
44

55
<chapter id="monitoring">
@@ -28,7 +28,8 @@ $PostgreSQL: pgsql/doc/src/sgml/monitoring.sgml,v 1.25 2003/11/29 19:51:37 pgsql
2828
but one should not neglect regular Unix monitoring programs such as
2929
<command>ps</> and <command>top</>. Also, once one has identified a
3030
poorly-performing query, further investigation may be needed using
31-
<productname>PostgreSQL</productname>'s <command>EXPLAIN</> command.
31+
<productname>PostgreSQL</productname>'s <xref linkend="sql-explain"
32+
endterm="sql-explain-title"> command.
3233
<xref linkend="using-explain"> discusses <command>EXPLAIN</>
3334
and other methods for understanding the behavior of an individual
3435
query.
@@ -126,28 +127,30 @@ postgres: <replaceable>user</> <replaceable>database</> <replaceable>host</> <re
126127
</para>
127128

128129
<para>
129-
The parameter <varname>stats_start_collector</varname> must be set to
130-
<literal>true</> for the statistics collector to
131-
be launched at all. This is the default and recommended setting,
132-
but it may be turned off if you have no interest in statistics and
133-
want to squeeze out every last drop of overhead. (The savings is
134-
likely to be small, however.) Note that this option
135-
cannot be changed while the server is running.
130+
The parameter <xref linkend="guc-stats-start-collector"> must be
131+
set to <literal>true</> for the statistics collector to be launched
132+
at all. This is the default and recommended setting, but it may be
133+
turned off if you have no interest in statistics and want to
134+
squeeze out every last drop of overhead. (The savings is likely to
135+
be small, however.) Note that this option cannot be changed while
136+
the server is running.
136137
</para>
137138

138139
<para>
139-
The parameters <varname>stats_command_string</varname>,
140-
<varname>stats_block_level</varname>,
141-
and <varname>stats_row_level</varname> control how much information is
140+
The parameters <xref linkend="guc-stats-command-string">,
141+
<xref linkend="guc-stats-block-level">, and <xref
142+
linkend="guc-stats-row-level"> control how much information is
142143
actually sent to the collector and thus determine how much run-time
143-
overhead occurs. These respectively determine whether a server process
144-
sends its current command string, disk-block-level access statistics, and
145-
row-level access statistics to the collector. Normally these parameters are
146-
set in <filename>postgresql.conf</> so that they apply to all server
147-
processes, but it is possible to turn them on or off in individual sessions
148-
using the <command>SET</> command. (To prevent ordinary users
149-
from hiding their activity from the administrator, only superusers are
150-
allowed to change these parameters with <command>SET</>.)
144+
overhead occurs. These respectively determine whether a server
145+
process sends its current command string, disk-block-level access
146+
statistics, and row-level access statistics to the collector.
147+
Normally these parameters are set in <filename>postgresql.conf</>
148+
so that they apply to all server processes, but it is possible to
149+
turn them on or off in individual sessions using the <xref
150+
linkend="sql-set" endterm="sql-set-title"> command. (To prevent
151+
ordinary users from hiding their activity from the administrator,
152+
only superusers are allowed to change these parameters with
153+
<command>SET</>.)
151154
</para>
152155

153156
<note>

‎doc/src/sgml/plpgsql.sgml

Lines changed: 3 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,5 @@
11
<!--
2-
$PostgreSQL: pgsql/doc/src/sgml/plpgsql.sgml,v 1.36 2004/02/27 03:59:23 neilc Exp $
2+
$PostgreSQL: pgsql/doc/src/sgml/plpgsql.sgml,v 1.37 2004/03/26 03:18:28 neilc Exp $
33
-->
44

55
<chapter id="plpgsql">
@@ -128,7 +128,8 @@ END;
128128
<para>
129129
The <application>PL/pgSQL</application>
130130
<command>EXECUTE</command> statement is not related to the
131-
<command>EXECUTE</command> statement supported by the
131+
<xref linkend="sql-execute" endterm="sql-execute-title"> SQL
132+
statement supported by the
132133
<productname>PostgreSQL</productname> server. The server's
133134
<command>EXECUTE</command> statement cannot be used within
134135
<application>PL/pgSQL</> functions (and is not needed).

‎doc/src/sgml/runtime.sgml

Lines changed: 81 additions & 42 deletions
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,5 @@
11
<!--
2-
$PostgreSQL: pgsql/doc/src/sgml/runtime.sgml,v 1.254 2004/03/24 22:40:28 tgl Exp $
2+
$PostgreSQL: pgsql/doc/src/sgml/runtime.sgml,v 1.255 2004/03/26 03:18:28 neilc Exp $
33
-->
44

55
<Chapter Id="runtime">
@@ -521,12 +521,14 @@ env PGOPTIONS='-c geqo=off' psql
521521
Furthermore, it is possible to assign a set of option settings to
522522
a user or a database. Whenever a session is started, the default
523523
settings for the user and database involved are loaded. The
524-
commands <command>ALTER DATABASE</command> and <command>ALTER
525-
USER</command>, respectively, are used to configure these
526-
settings. Per-database settings override anything received
527-
from the <command>postmaster</command> command-line or the
528-
configuration file, and in turn are overridden by per-user
529-
settings; both are overridden by per-session options.
524+
commands <xref linkend="sql-alterdatabase"
525+
endterm="sql-alterdatabase-title"> and <xref
526+
linkend="sql-alteruser" endterm="sql-alteruser-title">,
527+
respectively, are used to configure these settings. Per-database
528+
settings override anything received from the
529+
<command>postmaster</command> command-line or the configuration
530+
file, and in turn are overridden by per-user settings; both are
531+
overridden by per-session options.
530532
</para>
531533

532534
<para>
@@ -652,7 +654,7 @@ SET ENABLE_SEQSCAN TO OFF;
652654
server is to listen for
653655
connections from client applications. The default is normally
654656
<filename>/tmp</filename>, but can be changed at build time.
655-
This parameter can only be set at server start.
657+
This parameter can only be set at server start.
656658
</para>
657659
</listitem>
658660
</varlistentry>
@@ -711,10 +713,11 @@ SET ENABLE_SEQSCAN TO OFF;
711713
<term><varname>rendezvous_name</varname> (<type>string</type>)</term>
712714
<listitem>
713715
<para>
714-
Specifies the Rendezvous broadcast name. By default, the
715-
computer name is used, specified as an empty string ''.
716-
This option is only meaningful on platforms that support Rendezvous.
717-
This option can only be set at server start.
716+
Specifies the <productname>Rendezvous</productname> broadcast
717+
name. By default, the computer name is used, specified as an
718+
empty string ''. This option is only meaningful on platforms
719+
that support <productname>Rendezvous</productname>. This
720+
option can only be set at server start.
718721
</para>
719722
</listitem>
720723
</varlistentry>
@@ -759,10 +762,13 @@ SET ENABLE_SEQSCAN TO OFF;
759762
<term><varname>password_encryption</varname> (<type>boolean</type>)</term>
760763
<listitem>
761764
<para>
762-
When a password is specified in <command>CREATE USER</> or
763-
<command>ALTER USER</> without writing either <literal>ENCRYPTED</> or
764-
<literal>UNENCRYPTED</>, this option determines whether the password is to be
765-
encrypted. The default is on (encrypt the password).
765+
When a password is specified in <xref
766+
linkend="sql-createuser" endterm="sql-createuser-title"> or
767+
<xref linkend="sql-alteruser" endterm="sql-alteruser-title">
768+
without writing either <literal>ENCRYPTED</> or
769+
<literal>UNENCRYPTED</>, this option determines whether the
770+
password is to be encrypted. The default is on (encrypt the
771+
password).
766772
</para>
767773
</listitem>
768774
</varlistentry>
@@ -1010,13 +1016,14 @@ SET ENABLE_SEQSCAN TO OFF;
10101016
<title>Cost-Based Vacuum Delay</title>
10111017

10121018
<para>
1013-
During the execution of <command>VACUUM</command>
1014-
and <command>ANALYZE</command> commands,
1015-
the system maintains an internal counter that keeps track of the
1016-
estimated cost of the various I/O operations that are performed.
1017-
When the accumulated cost reaches a limit
1018-
(specified by <varname>vacuum_cost_limit</varname>), the process
1019-
performing the operation will sleep for a while (specified by
1019+
During the execution of <xref linkend="sql-vacuum"
1020+
endterm="sql-vacuum-title"> and <xref linkend="sql-analyze"
1021+
endterm="sql-analyze-title"> commands, the system maintains an
1022+
internal counter that keeps track of the estimated cost of the
1023+
various I/O operations that are performed. When the accumulated
1024+
cost reaches a limit (specified by
1025+
<varname>vacuum_cost_limit</varname>), the process performing
1026+
the operation will sleep for a while (specified by
10201027
<varname>vacuum_cost_naptime</varname>). Then it will reset the
10211028
counter and continue execution.
10221029
</para>
@@ -1306,10 +1313,13 @@ SET ENABLE_SEQSCAN TO OFF;
13061313
choose a better plan. Other ways to improve the quality of the
13071314
plans chosen by the optimizer include configuring the <xref
13081315
linkend="runtime-config-query-constants"
1309-
endterm="runtime-config-query-constants-title">, running
1310-
<command>ANALYZE</command> more frequently, and increasing the
1311-
amount of statistics collected for a particular column using
1312-
<command>ALTER TABLE SET STATISTICS</command>.
1316+
endterm="runtime-config-query-constants-title">, running <xref
1317+
linkend="sql-analyze" endterm="sql-analyze-title"> more
1318+
frequently, increasing the value of the <xref
1319+
linkend="guc-default-statistics-target"> configuration parameter,
1320+
and increasing the amount of statistics collected for a
1321+
particular column using <command>ALTER TABLE SET
1322+
STATISTICS</command>.
13131323
</para>
13141324
</note>
13151325

@@ -2115,13 +2125,27 @@ SET ENABLE_SEQSCAN TO OFF;
21152125
<term><varname>log_statement</varname> (<type>boolean</type>)</term>
21162126
<listitem>
21172127
<para>
2118-
Causes each SQL statement to be logged. The default is off.
2119-
<command>EXECUTE</> only displays the plan name, not the
2120-
prepared query. Server-side languages like
2121-
<application>PL/pgSQL</> that store functions in a cache only
2122-
display their queries on first function call. Only superusers can
2123-
turn off this option if it is enabled by the administrator.
2128+
Causes each SQL statement to be logged. The default is
2129+
off. Only superusers can disable this option if it has been
2130+
enabled by an administrator.
21242131
</para>
2132+
2133+
<note>
2134+
<para>
2135+
When the <command>EXECUTE</command> statement is logged, only
2136+
the name of the prepared statement is recorded, not the
2137+
entire prepared statement.
2138+
</para>
2139+
2140+
<para>
2141+
When a function is defined in a server-side language like
2142+
<application>PL/pgSQL</application>, any queries executed by
2143+
the function will only be logged the first time that the
2144+
function is invoked in a particular session. This is because
2145+
the <application>PL/pgSQL</application> keeps a cache of the
2146+
query plans produced for the SQL statements in the function.
2147+
</para>
2148+
</note>
21252149
</listitem>
21262150
</varlistentry>
21272151

@@ -2202,14 +2226,27 @@ SET ENABLE_SEQSCAN TO OFF;
22022226
</listitem>
22032227
</varlistentry>
22042228

2205-
<varlistentry>
2229+
<varlistentry id="guc-stats-block-level" xreflabel="guc_stats_block_level">
22062230
<term><varname>stats_block_level</varname> (<type>boolean</type>)</term>
2231+
<listitem>
2232+
<para>
2233+
Enables the collection of block-level statistics on database
2234+
activity. This option is disabled by default. If this option
2235+
is enabled, the data that is produced can be accessed via the
2236+
<structname>pg_stat</structname> and
2237+
<structname>pg_statio</structname> family of system views;
2238+
refer to <xref linkend="monitoring"> for more information.
2239+
</para>
2240+
</listitem>
2241+
</varlistentry>
2242+
2243+
<varlistentry id="guc-stats-row-level" xreflabel="guc_stats_row_level">
22072244
<term><varname>stats_row_level</varname> (<type>boolean</type>)</term>
22082245
<listitem>
22092246
<para>
2210-
These enable the collection of block-level and row-level statistics
2211-
on database activity, respectively. These options are off by
2212-
default. This data can be accessed via the
2247+
Enables the collection of row-level statistics on database
2248+
activity. This option is disabled by default. If this option
2249+
is enabled, the data that is produced can be accessed via the
22132250
<structname>pg_stat</structname> and
22142251
<structname>pg_statio</structname> family of system views;
22152252
refer to <xref linkend="monitoring"> for more information.
@@ -2311,10 +2348,12 @@ SET ENABLE_SEQSCAN TO OFF;
23112348
<term><varname>check_function_bodies</varname> (<type>boolean</type>)</term>
23122349
<listitem>
23132350
<para>
2314-
This parameter is normally true. When set false, it disables
2315-
validation of the function body string in <command>CREATE FUNCTION</>.
2316-
Disabling validation is occasionally useful to avoid problems such as
2317-
forward references when restoring function definitions from a dump.
2351+
This parameter is normally true. When set to false, it disables
2352+
validation of the function body string in <xref
2353+
linkend="sql-createfunction"
2354+
endterm="sql-createfunction-title">. Disabling validation is
2355+
occasionally useful to avoid problems such as forward
2356+
references when restoring function definitions from a dump.
23182357
</para>
23192358
</listitem>
23202359
</varlistentry>
@@ -2503,7 +2542,7 @@ SET ENABLE_SEQSCAN TO OFF;
25032542
<listitem>
25042543
<para>
25052544
Sets the locale to use for formatting numbers, for example
2506-
with the <function>to_char()</function> family of
2545+
with the <function>to_char</function> family of
25072546
functions. Acceptable values are system-dependent; see <xref
25082547
linkend="locale"> for more information. If this variable is
25092548
set to the empty string (which is the default) then the value

0 commit comments

Comments
 (0)
0