Skip to content

P
Postgres FD Implementation
Commit 0a404864 authored by Tom Lane's avatar Tom Lane
Browse files
Options

Document all the system views created by initdb (several of these were 

never documented anywhere, sigh).  Centralize the detailed documentation
of system views into catalogs.sgml, and provide cross-references.
parent e5c2c978
Expand all Hide whitespace changes
Inline Side-by-side
Showing with 858 additions and 334 deletions
doc/src/sgml/catalogs.sgml
View file @ 0a404864
This diff is collapsed.
doc/src/sgml/monitoring.sgml
View file @ 0a404864
<!--
$Header: /cvsroot/pgsql/doc/src/sgml/monitoring.sgml,v 1.21 2003/08/31 17:32:19 petere Exp $
$Header: /cvsroot/pgsql/doc/src/sgml/monitoring.sgml,v 1.22 2003/10/17 22:38:20 tgl Exp $
-->
<chapter id="monitoring">
......@@ -606,7 +606,7 @@ SELECT pg_stat_get_backend_pid(s.backendid) AS procpid,
<para>
Another useful tool for monitoring database activity is the
<literal>pg_locks</literal> system table. It allows the
<structname>pg_locks</structname> system table. It allows the
database administrator to view information about the outstanding
locks in the lock manager. For example, this capability can be used
to:
......@@ -638,130 +638,11 @@ SELECT pg_stat_get_backend_pid(s.backendid) AS procpid,
</listitem>
</itemizedlist>
Details of the <structname>pg_locks</structname> view appear in
<xref linkend="view-pg-locks">.
For more information on locking and managing concurrency with
<productname>PostgreSQL</productname>, refer to <xref linkend="mvcc">.
</para>
<note>
<para>
When the <literal>pg_locks</literal> view is accessed, the
internal lock manager data structures are momentarily locked, and
a copy is made for the view to display. This ensures that the
view produces a consistent set of results, while not blocking
normal lock manager operations longer than necessary. Nonetheless
there could be some impact on database performance if this view is
read often.
</para>
</note>
<para>
<xref linkend="monitoring-locks-table"> shows the definition of the
<literal>pg_locks</literal> columns. The
<literal>pg_locks</literal> view contains one row per lockable
object and requested lock mode. Thus, the same lockable object may
appear many times, if multiple transactions are holding or waiting
for locks on it. A lockable object is either a relation (e.g., a table) or a
transaction ID. (Note that this view includes only table-level
locks, not row-level ones. If a transaction is waiting for a
row-level lock, it will appear in the view as waiting for the
transaction ID of the current holder of that row lock.)
</para>
<table id="monitoring-locks-table">
<title><literal>pg_locks</literal> Columns</title>
<tgroup cols="3">
<thead>
<row>
<entry>Column Name</entry>
<entry>Data Type</entry>
<entry>Description</entry>
</row>
</thead>
<tbody>
<row>
<entry><structfield>relation</structfield></entry>
<entry><type>oid</type></entry>
<entry>
The OID of the locked relation, or null if the lockable object
is a transaction ID. This column can be joined with the column <literal>oid</> of the
<literal>pg_class</literal> system catalog to get more
information on the locked relation. Note however that this
will only work for relations in the current database (those for
which the <structfield>database</structfield> column is either
the current database's OID or zero).
</entry>
</row>
<row>
<entry><structfield>database</structfield></entry>
<entry><type>oid</type></entry>
<entry>
The OID of the database in which the locked relation exists, or
null if the lockable object is a transaction ID. If the lock
is on a globally-shared table, this field will be zero. This
column can be joined with the column <literal>oid</> of the <literal>pg_database</literal>
system catalog to get more information on the locked object's
database.
</entry>
</row>
<row>
<entry><structfield>transaction</structfield></entry>
<entry><type>xid</type></entry>
<entry>
The ID of a transaction, or null if the lockable object is a
relation. Every transaction holds an exclusive lock on its
transaction ID for its entire duration. If one transaction
finds it necessary to wait specifically for another
transaction, it does so by attempting to acquire share lock on
the other transaction ID. That will succeed only when the
other transaction terminates and releases its locks.
</entry>
</row>
<row>
<entry><structfield>pid</structfield></entry>
<entry><type>integer</type></entry>
<entry>
The process ID of the <productname>PostgreSQL</productname>
server process belonging to the session that has acquired or is
attempting to acquire the lock. If you have enabled the
statistics collector, this column can be joined with the column
<literal>pg_stat_activity</literal> view to get more
information on the session holding or waiting to hold the
lock.
</entry>
</row>
<row>
<entry><structfield>mode</structfield></entry>
<entry><type>text</type></entry>
<entry>
The mode of the requested or held lock on the lockable
object. For more information on the different lock modes
available in <productname>PostgreSQL</productname>, refer to
<xref linkend="mvcc">.
</entry>
</row>
<row>
<entry><structfield>isgranted</structfield></entry>
<entry><type>boolean</type></entry>
<entry>
True if this lock has been granted (is held by this session).
False indicates that this session is currently waiting to
acquire this lock, which implies that some other session is
holding a conflicting lock mode on the same lockable object.
The waiting session will sleep until the other lock is released (or a
deadlock situation is detected). A single session can be
waiting to acquire at most one lock at a time.
</entry>
</row>
</tbody>
</tgroup>
</table>
</sect1>
</chapter>
......
doc/src/sgml/mvcc.sgml
View file @ 0a404864
<!--
$Header: /cvsroot/pgsql/doc/src/sgml/mvcc.sgml,v 2.38 2003/09/20 20:12:05 tgl Exp $
$Header: /cvsroot/pgsql/doc/src/sgml/mvcc.sgml,v 2.39 2003/10/17 22:38:20 tgl Exp $
-->
<chapter id="mvcc">
......@@ -399,6 +399,14 @@ ERROR: could not serialize access due to concurrent update
executed concurrently with other operations on the same table.)
</para>
<para>
To examine a list of the currently outstanding locks in a database
server, use the <structname>pg_locks</structname> system view
(<xref linkend="view-pg-locks">). For more
information on monitoring the status of the lock manager
subsystem, refer to <xref linkend="monitoring">.
</para>
<sect2 id="locking-tables">
<title>Table-Level Locks</title>
......@@ -429,13 +437,6 @@ ERROR: could not serialize access due to concurrent update
Once acquired, a lock is held till end of transaction.
</para>
<para>
To examine a list of the currently outstanding locks in a database
server, use the <literal>pg_locks</literal> system view. For more
information on monitoring the status of the lock manager
subsystem, refer to <xref linkend="monitoring">.
</para>
<variablelist>
<title>Table-level lock modes</title>
<varlistentry>
......
doc/src/sgml/perform.sgml
View file @ 0a404864
<!--
$Header: /cvsroot/pgsql/doc/src/sgml/perform.sgml,v 1.35 2003/10/17 01:14:26 tgl Exp $
$Header: /cvsroot/pgsql/doc/src/sgml/perform.sgml,v 1.36 2003/10/17 22:38:20 tgl Exp $
-->
<chapter id="performance-tips">
......@@ -439,114 +439,19 @@ SELECT attname, n_distinct, most_common_vals FROM pg_stats WHERE tablename = 'ro
</para>
<para>
<xref linkend="planner-pg-stats-table"> shows the columns that
exist in <structname>pg_stats</structname>.
<structname>pg_stats</structname> is described in detail in
<xref linkend="view-pg-stats">.
</para>
<table id="planner-pg-stats-table">
<title><structname>pg_stats</structname> Columns</title>
<tgroup cols=3>
<thead>
<row>
<entry>Name</entry>
<entry>Data Type</entry>
<entry>Description</entry>
</row>
</thead>
<tbody>
<row>
<entry><literal>schemaname</literal></entry>
<entry><type>name</type></entry>
<entry>Name of the schema containing the table.</entry>
</row>
<row>
<entry><literal>tablename</literal></entry>
<entry><type>name</type></entry>
<entry>Name of the table containing the column.</entry>
</row>
<row>
<entry><literal>attname</literal></entry>
<entry><type>name</type></entry>
<entry>Name of the column described by this row.</entry>
</row>
<row>
<entry><literal>null_frac</literal></entry>
<entry><type>real</type></entry>
<entry>Fraction of column entries that are null.</entry>
</row>
<row>
<entry><literal>avg_width</literal></entry>
<entry><type>integer</type></entry>
<entry>Average width in bytes of the column entries.</entry>
</row>
<row>
<entry><literal>n_distinct</literal></entry>
<entry><type>real</type></entry>
<entry>If greater than zero, the estimated number of distinct values
in the column. If less than zero, the negative of the number of
distinct values divided by the number of rows. (The negated form
is used when <command>ANALYZE</> believes that the number of distinct values
is likely to increase as the table grows; the positive form is used
when the column seems to have a fixed number of possible values.)
For example, -1 indicates a unique column in which the number of
distinct values is the same as the number of rows.
</entry>
</row>
<row>
<entry><literal>most_common_vals</literal></entry>
<entry><type>text[]</type></entry>
<entry>A list of the most common values in the column. (Omitted if
no values seem to be more common than any others.)</entry>
</row>
<row>
<entry><literal>most_common_freqs</literal></entry>
<entry><type>real[]</type></entry>
<entry>A list of the frequencies of the most common values,
i.e., number of occurrences of each divided by total number of rows.
</entry>
</row>
<row>
<entry><literal>histogram_bounds</literal></entry>
<entry><type>text[]</type></entry>
<entry>A list of values that divide the column's values into
groups of approximately equal population. The values in
<structfield>most_common_vals</>, if present, are omitted from this
histogram calculation. (This columns is not filled if the column data type does not have a
<literal>&lt;</> operator or if the <structfield>most_common_vals</>
list accounts for the entire population.)
</entry>
</row>
<row>
<entry><literal>correlation</literal></entry>
<entry><type>real</type></entry>
<entry>Statistical correlation between physical row ordering and
logical ordering of the column values. This ranges from -1 to +1.
When the value is near -1 or +1, an index scan on the column will
be estimated to be cheaper than when it is near zero, due to reduction
of random access to the disk. (This column is not filled if the column data type does
not have a <literal>&lt;</> operator.)
</entry>
</row>
</tbody>
</tgroup>
</table>
<para>
The maximum number of entries in the <structfield>most_common_vals</>
and <structfield>histogram_bounds</> arrays can be set on a
The amount of information stored in <structname>pg_statistic</structname>,
in particular the maximum number of entries in the
<structfield>most_common_vals</> and <structfield>histogram_bounds</>
arrays for each column, can be set on a
column-by-column basis using the <command>ALTER TABLE SET STATISTICS</>
command. The default limit is presently 10 entries. Raising the limit
command, or globally by setting the
<varname>default_statistics_target</varname> runtime parameter.
The default limit is presently 10 entries. Raising the limit
may allow more accurate planner estimates to be made, particularly for
columns with irregular data distributions, at the price of consuming
more space in <structname>pg_statistic</structname> and slightly more
......
doc/src/sgml/runtime.sgml
View file @ 0a404864
<!--
$Header: /cvsroot/pgsql/doc/src/sgml/runtime.sgml,v 1.213 2003/10/10 02:08:42 momjian Exp $
$Header: /cvsroot/pgsql/doc/src/sgml/runtime.sgml,v 1.214 2003/10/17 22:38:20 tgl Exp $
-->
<Chapter Id="runtime">
......@@ -466,7 +466,7 @@ psql: could not connect to server: No such file or directory
</para>
<para>
One way to set these options is to edit the file
One way to set these parameters is to edit the file
<filename>postgresql.conf</filename><indexterm><primary>postgresql.conf</></>
in the data directory. (A default file is installed there.) An
example of what this file might look like is:
......@@ -476,7 +476,7 @@ log_connections = yes
syslog = 2
search_path = '$user, public'
</programlisting>
One option is specified per line. The equal sign between name and
One parameter is specified per line. The equal sign between name and
value is optional. Whitespace is insignificant and blank lines are
ignored. Hash marks (<literal>#</literal>) introduce comments
anywhere. Parameter values that are not simple identifiers or
......@@ -517,110 +517,47 @@ env PGOPTIONS='-c geqo=off' psql
</programlisting>
(This works for any <application>libpq</>-based client application, not just
<application>psql</application>.) Note that this won't work for
options that are fixed when the server is started, such as the port
parameters that are fixed when the server is started, such as the port
number.
</para>
<para>
Some options can be changed in individual <acronym>SQL</acronym>
sessions with the <command>SET</command> command, for example:
<screen>
SET ENABLE_SEQSCAN TO OFF;
</screen>
See the <acronym>SQL</acronym> command language reference for
details on the syntax.
</para>
<para>
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. Such per-database settings override anything received
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.
settings; both are overridden by per-session options.
</para>
<para>
The virtual table <structname>pg_settings</structname> allows
displaying and updating session run-time parameters. It contains one
row for each configuration parameter; the columns are shown in
<xref linkend="runtime-pgsettings-table">. This table allows the
configuration data to be joined with other tables and have a
selection criteria applied.
Some parameters can be changed in individual <acronym>SQL</acronym>
sessions with the <xref linkend="SQL-SET" endterm="SQL-SET-title">
command, for example:
<screen>
SET ENABLE_SEQSCAN TO OFF;
</screen>
If <command>SET</> is allowed, it overrides all other sources of
values for the parameter. Superusers are allowed to <command>SET</>
more values than ordinary users.
</para>
<para>
An <command>UPDATE</command> performed on <structname>pg_settings</structname>
is equivalent to executing the <command>SET</command> command on that named
parameter. The change only affects the value used by the current session. If
an <command>UPDATE</command> is issued within a transaction that is later
aborted, the effects of the <command>UPDATE</command> command disappear when
the transaction is rolled back. Once the surrounding transaction is
committed, the effects will persist until the end of the session, unless
overridden by another <command>UPDATE</command> or <command>SET</command>.
</para>
<table id="runtime-pgsettings-table">
<title><literal>pg_settings</> Columns</title>
<tgroup cols=3>
<thead>
<row>
<entry>Name</entry>
<entry>Data Type</entry>
<entry>Description</entry>
</row>
</thead>
<tbody>
<row>
<entry><literal>name</literal></entry>
<entry><type>text</type></entry>
<entry>run-time configuration parameter name</entry>
</row>
<row>
<entry><literal>setting</literal></entry>
<entry><type>text</type></entry>
<entry>current value of the parameter</entry>
</row>
<row>
<entry><literal>context</literal></entry>
<entry><type>text</type></entry>
<entry>context required to set the parameter's value</entry>
</row>
<row>
<entry><literal>vartype</literal></entry>
<entry><type>text</type></entry>
<entry>parameter type</entry>
</row>
<row>
<entry><literal>source</literal></entry>
<entry><type>text</type></entry>
<entry>source of the current parameter value</entry>
</row>
<row>
<entry><literal>min_val</literal></entry>
<entry><type>text</type></entry>
<entry>minimum allowed value of the parameter</entry>
</row>
<row>
<entry><literal>max_val</literal></entry>
<entry><type>text</type></entry>
<entry>maximum allowed value of the parameter</entry>
</row>
<para>
The <xref linkend="SQL-SHOW" endterm="SQL-SHOW-title">
command allows inspection of the current values of all parameters.
</para>
</tbody>
</tgroup>
</table>
<para>
The virtual table <structname>pg_settings</structname>
(described in <xref linkend="view-pg-settings">) also allows
displaying and updating session run-time parameters. It is equivalent
to <command>SHOW</> and <command>SET</>, but can be more convenient
to use because it can be joined with other tables, or selected from using
any desired selection condition.
</para>
<sect2 id="runtime-config-connection">
<title>Connections and Authentication</title>
......
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment