Add note about pg_stats to pg_statistic entry; add sections for

pg_largeobject, pg_listener, pg_rewrite, pg_trigger; miscellaneous
small improvements.
This commit is contained in:
Tom Lane 2001-10-15 22:47:47 +00:00
parent e158670c1f
commit daf72bba91
1 changed files with 432 additions and 28 deletions

View File

@ -1,6 +1,6 @@
<!--
Documentation of the system catalogs, directed toward PostgreSQL developers
$Header: /cvsroot/pgsql/doc/src/sgml/catalogs.sgml,v 2.25 2001/09/13 15:55:22 petere Exp $
$Header: /cvsroot/pgsql/doc/src/sgml/catalogs.sgml,v 2.26 2001/10/15 22:47:47 tgl Exp $
-->
<chapter id="catalogs">
@ -63,7 +63,7 @@
<row>
<entry>pg_attribute</entry>
<entry>table columns (attributes, fields)</entry>
<entry>table columns (<quote>attributes</quote>, <quote>fields</quote>)</entry>
</row>
<row>
@ -73,7 +73,7 @@
<row>
<entry>pg_database</entry>
<entry>databases</entry>
<entry>databases within this database cluster</entry>
</row>
<row>
@ -83,7 +83,7 @@
<row>
<entry>pg_group</entry>
<entry>user groups</entry>
<entry>groups of database users</entry>
</row>
<row>
@ -162,8 +162,7 @@
<para>
More detailed documentation of most catalogs follow below. The
catalogs that relate to index access methods are explained in the
<citetitle>Programmer's Guide</citetitle>. Some catalogs don't
have any documentation, yet.
<citetitle>Programmer's Guide</citetitle>.
</para>
</section>
@ -210,13 +209,13 @@
<row>
<entry>aggtransfn</entry>
<entry><type>regproc</type> (function)</entry>
<entry></entry>
<entry>pg_proc.oid</entry>
<entry>Transition function</entry>
</row>
<row>
<entry>aggfinalfn</entry>
<entry><type>regproc</type> (function)</entry>
<entry></entry>
<entry>pg_proc.oid</entry>
<entry>Final function</entry>
</row>
<row>
@ -431,7 +430,7 @@
<entry></entry>
<entry>
Always -1 in storage, but when loaded into a tuple descriptor
in memory this may be updated cache the offset of the attribute
in memory this may be updated to cache the offset of the attribute
within the tuple.
</entry>
</row>
@ -653,7 +652,8 @@
<entry><type>bool</type></entry>
<entry></entry>
<entry>True if this table is shared across all databases in the
cluster.</entry>
cluster. Only certain system catalogs (such as
<structname>pg_database</structname>) are shared.</entry>
</row>
<row>
@ -741,7 +741,9 @@
<entry>relhasrules</entry>
<entry><type>bool</type></entry>
<entry></entry>
<entry>Table has rules</entry>
<entry>Table has rules; see
<structname>pg_rewrite</structname> catalog
</entry>
</row>
<row>
@ -772,14 +774,19 @@
<para>
The <structname>pg_database</structname> catalog stores information
about the available databases. The
<structname>pg_database</structname> table is shared between all
databases of a cluster. Databases are created with the
<command>CREATE DATABASE</command>. Consult the
about the available databases. Databases are created with the
<command>CREATE DATABASE</command> command. Consult the
<citetitle>Administrator's Guide</citetitle> for details about the
meaning of some of the parameters.
</para>
<para>
Unlike most system catalogs, <structname>pg_database</structname>
is shared across all databases of a cluster: there is only one
copy of <structname>pg_database</structname> per cluster, not
one per database.
</para>
<table>
<title>pg_database Columns</title>
@ -959,6 +966,14 @@
Guide</citetitle> for information about user permission management.
</para>
<para>
Because user and group identities are cluster-wide,
<structname>pg_group</structname>
is shared across all databases of a cluster: there is only one
copy of <structname>pg_group</structname> per cluster, not
one per database.
</para>
<table>
<title>pg_group Columns</title>
@ -1039,7 +1054,7 @@
<row>
<entry>indproc</entry>
<entry><type>oid</type></entry>
<entry><type>regproc</type></entry>
<entry>pg_proc.oid</entry>
<entry>The registered procedure if this is a functional index</entry>
</row>
@ -1086,7 +1101,8 @@
<entry>indisprimary</entry>
<entry><type>bool</type></entry>
<entry></entry>
<entry>If true, this index is a unique index that represents the primary key of the table.</entry>
<entry>If true, this index represents the primary key of the table.
(indisunique should always be true when this is true.)</entry>
</row>
<row>
@ -1147,7 +1163,7 @@
<entry><type>oid</type></entry>
<entry>pg_class.oid</entry>
<entry>
This is the reference to the parent table, from which the table
This is the reference to the parent table, which the table
referenced by <structfield>inhrelid</structfield> inherited
from.
</entry>
@ -1158,7 +1174,7 @@
<entry><type>int4</type></entry>
<entry></entry>
<entry>
If there is more than one subtable/parent pair (multiple
If there is more than one parent for a subtable (multiple
inheritance), this number tells the order in which the
inherited columns are to be arranged. The count starts at 1.
</entry>
@ -1250,6 +1266,132 @@
</section>
<section id="catalog-pg-largeobject">
<title>pg_largeobject</title>
<para>
<structname>pg_largeobject</structname> holds the data making up
<quote>large objects</quote>. A large object is identified by an
OID assigned when it is created. Each large object is broken into
segments or <quote>pages</> small enough to be conveniently stored as rows
in <structname>pg_largeobject</structname>.
The amount of data per page is defined to be LOBLKSIZE (which is currently
BLCKSZ/4, or typically 2Kbytes).
</para>
<table>
<title>pg_largeobject Columns</title>
<tgroup cols=4>
<thead>
<row>
<entry>Name</entry>
<entry>Type</entry>
<entry>References</entry>
<entry>Description</entry>
</row>
</thead>
<tbody>
<row>
<entry>loid</entry>
<entry><type>oid</type></entry>
<entry></entry>
<entry>Identifier of the large object that includes this page</entry>
</row>
<row>
<entry>pageno</entry>
<entry><type>int4</type></entry>
<entry></entry>
<entry>Page number of this page within its large object
(counting from zero)</entry>
</row>
<row>
<entry>data</entry>
<entry><type>bytea</type></entry>
<entry></entry>
<entry>
Actual data stored in the large object.
This will never be more than LOBLKSIZE bytes, and may be less.
</entry>
</row>
</tbody>
</tgroup>
</table>
<para>
Each row of <structname>pg_largeobject</structname> holds data
for one page of a large object, beginning at
byte offset (pageno * LOBLKSIZE) within the object. The implementation
allows sparse storage: pages may be missing, and may be shorter than
LOBLKSIZE bytes even if they are not the last page of the object.
Missing regions within a large object read as zeroes.
</para>
</section>
<section id="catalog-pg-listener">
<title>pg_listener</title>
<para>
<structname>pg_listener</structname> supports the <command>LISTEN</>
and <command>NOTIFY</> commands. A listener creates an entry in
<structname>pg_listener</structname> for each notification name
it is listening for. A notifier scans <structname>pg_listener</structname>
and updates each matching entry to show that a notification has occurred.
The notifier also sends a signal (using the PID recorded in the table)
to awaken the listener from sleep.
</para>
<table>
<title>pg_listener Columns</title>
<tgroup cols=4>
<thead>
<row>
<entry>Name</entry>
<entry>Type</entry>
<entry>References</entry>
<entry>Description</entry>
</row>
</thead>
<tbody>
<row>
<entry>relname</entry>
<entry><type>name</type></entry>
<entry></entry>
<entry>Notify condition name. (The name need not match any actual
relation in the database; the term <quote>relname</> is historical.)
</entry>
</row>
<row>
<entry>listenerpid</entry>
<entry><type>int4</type></entry>
<entry></entry>
<entry>PID of the backend process that created this entry.</entry>
</row>
<row>
<entry>notification</entry>
<entry><type>int4</type></entry>
<entry></entry>
<entry>
Zero if no event is pending for this listener. If an event is
pending, the PID of the backend that sent the notification.
</entry>
</row>
</tbody>
</tgroup>
</table>
</section>
<section id="catalog-pg-operator">
<title>pg_operator</title>
@ -1489,7 +1631,8 @@
<entry>proretset</entry>
<entry><type>bool</type></entry>
<entry></entry>
<entry>Function returns a set (probably not functional)</entry>
<entry>Function returns a set (ie, multiple values of the specified
datatype)</entry>
</row>
<row>
@ -1542,7 +1685,7 @@
This tells the function handler how to invoke the function. It
might be the actual source code of the function for interpreted
languages, a link symbol, a file name, or just about anything
else, depending the implementation language/call convention.
else, depending on the implementation language/call convention.
</entry>
</row>
@ -1550,12 +1693,26 @@
<entry>probin</entry>
<entry><type>bytea</type></entry>
<entry></entry>
<entry>?</entry>
<entry>Additional information about how to invoke the function.
Again, the interpretation is language-specific.
</entry>
</row>
</tbody>
</tgroup>
</table>
<para>
Currently, prosrc contains the function's C-language name (link symbol)
for compiled functions, both built-in and dynamically loaded. For all
other language types, prosrc contains the function's source text.
</para>
<para>
Currently, probin is unused except for dynamically-loaded C functions,
for which it gives the name of the shared library file containing the
function.
</para>
</section>
@ -1608,7 +1765,7 @@
<entry>rcsrc</entry>
<entry><type>text</type></entry>
<entry></entry>
<entry>A human-readable representation of the consraint expression</entry>
<entry>A human-readable representation of the constraint expression</entry>
</row>
</tbody>
</tgroup>
@ -1624,6 +1781,93 @@
</section>
<section id="catalog-pg-rewrite">
<title>pg_rewrite</title>
<para>
This system catalog stores rewrite rules for tables and views.
</para>
<table>
<title>pg_rewrite Columns</title>
<tgroup cols=4>
<thead>
<row>
<entry>Name</entry>
<entry>Type</entry>
<entry>References</entry>
<entry>Description</entry>
</row>
</thead>
<tbody>
<row>
<entry>rulename</entry>
<entry><type>name</type></entry>
<entry></entry>
<entry>Rule name</entry>
</row>
<row>
<entry>ev_type</entry>
<entry><type>char</type></entry>
<entry></entry>
<entry>Event type that the rule is for: '1' = SELECT,
'2' = UPDATE, '3' = INSERT, '4' = DELETE</entry>
</row>
<row>
<entry>ev_class</entry>
<entry><type>oid</type></entry>
<entry>pg_class.oid</entry>
<entry>The table this rule is for</entry>
</row>
<row>
<entry>ev_attr</entry>
<entry><type>int2</type></entry>
<entry></entry>
<entry>The column this rule is for (currently, always zero to
indicate the whole table)</entry>
</row>
<row>
<entry>is_instead</entry>
<entry><type>bool</type></entry>
<entry></entry>
<entry>True if the rule is an INSTEAD rule</entry>
</row>
<row>
<entry>ev_qual</entry>
<entry><type>text</type></entry>
<entry></entry>
<entry>Expression tree (in the form of a nodeToString representation)
for the rule's qualifying condition</entry>
</row>
<row>
<entry>ev_action</entry>
<entry><type>text</type></entry>
<entry></entry>
<entry>Query tree (in the form of a nodeToString representation)
for the rule's action</entry>
</row>
</tbody>
</tgroup>
</table>
<note>
<para>
<structname>pg_class</structname>.<structfield>relhasrules</structfield>
must be true if a table has any rules in this catalog.
</para>
</note>
</section>
<section id="catalog-pg-shadow">
<title>pg_shadow</title>
@ -1631,7 +1875,7 @@
<structname>pg_shadow</structname> contains information about
database users. The name stems from the fact that this table
should not be readable by the public since it contains passwords.
<structname>pg_user</structname> is a view on
<structname>pg_user</structname> is a publicly readable view on
<structname>pg_shadow</structname> that blanks out the password field.
</para>
@ -1640,6 +1884,14 @@
information about user and permission management.
</para>
<para>
Because user identities are cluster-wide,
<structname>pg_shadow</structname>
is shared across all databases of a cluster: there is only one
copy of <structname>pg_shadow</structname> per cluster, not
one per database.
</para>
<table>
<title>pg_shadow Columns</title>
@ -1743,6 +1995,20 @@
<filename>src/include/catalog/pg_statistic.h</filename>.
</para>
<para>
<structname>pg_statistic</structname> should not be readable by the
public, since even statistical information about a table's contents
may be considered sensitive. (Example: minimum and maximum values
of a salary column might be quite interesting.)
<structname>pg_stats</structname> is a publicly readable view on
<structname>pg_statistic</structname> that only exposes information
about those tables that are readable by the current user.
<structname>pg_stats</structname> is also designed to present the
information in a more readable format than the underlying
<structname>pg_statistic</structname> table --- at the cost that
its schema must be extended whenever new slot types are added.
</para>
<table>
<title>pg_statistic Columns</title>
@ -1843,9 +2109,144 @@
</section>
<section id="catalog-pg-trigger">
<title>pg_trigger</title>
<para>
This system catalog stores triggers on tables. See under
<command>CREATE TRIGGER</command> for more information.
</para>
<table>
<title>pg_trigger Columns</title>
<tgroup cols=4>
<thead>
<row>
<entry>Name</entry>
<entry>Type</entry>
<entry>References</entry>
<entry>Description</entry>
</row>
</thead>
<tbody>
<row>
<entry>tgrelid</entry>
<entry><type>oid</type></entry>
<entry>pg_class.oid</entry>
<entry>The table this trigger is on</entry>
</row>
<row>
<entry>tgname</entry>
<entry><type>name</type></entry>
<entry></entry>
<entry>Trigger name (need not be unique)</entry>
</row>
<row>
<entry>tgfoid</entry>
<entry><type>oid</type></entry>
<entry>pg_proc.oid</entry>
<entry>The function to be called</entry>
</row>
<row>
<entry>tgtype</entry>
<entry><type>int2</type></entry>
<entry></entry>
<entry>Bitmask identifying trigger conditions</entry>
</row>
<row>
<entry>tgenabled</entry>
<entry><type>bool</type></entry>
<entry></entry>
<entry>True if trigger is enabled (not presently checked everywhere
it should be, so disabling a trigger by setting this false does not
work reliably)</entry>
</row>
<row>
<entry>tgisconstraint</entry>
<entry><type>bool</type></entry>
<entry></entry>
<entry>True if trigger is a RI constraint</entry>
</row>
<row>
<entry>tgconstrname</entry>
<entry><type>name</type></entry>
<entry></entry>
<entry>RI constraint name</entry>
</row>
<row>
<entry>tgconstrrelid</entry>
<entry><type>oid</type></entry>
<entry>pg_class.oid</entry>
<entry>The table referenced by an RI constraint</entry>
</row>
<row>
<entry>tgdeferrable</entry>
<entry><type>bool</type></entry>
<entry></entry>
<entry>True if deferrable</entry>
</row>
<row>
<entry>tginitdeferred</entry>
<entry><type>bool</type></entry>
<entry></entry>
<entry>True if initially deferred</entry>
</row>
<row>
<entry>tgnargs</entry>
<entry><type>int2</type></entry>
<entry></entry>
<entry>Number of argument strings passed to trigger function</entry>
</row>
<row>
<entry>tgattr</entry>
<entry><type>int2vector</type></entry>
<entry></entry>
<entry>Currently unused</entry>
</row>
<row>
<entry>tgargs</entry>
<entry><type>bytea</type></entry>
<entry></entry>
<entry>Argument strings to pass to trigger, each null-terminated</entry>
</row>
</tbody>
</tgroup>
</table>
<note>
<para>
<structname>pg_class</structname>.<structfield>reltriggers</structfield>
needs to match up with the entries in this table.
</para>
</note>
</section>
<section id="catalog-pg-type">
<title>pg_type</title>
<para>
This catalog stores information about datatypes. Scalar types
(<quote>base types</>) are created with <command>CREATE TYPE</command>.
A complex type is also created for each table in the database, to
represent the row structure of the table.
</para>
<table>
<title>pg_type Columns</title>
@ -1913,8 +2314,8 @@
<entry></entry>
<entry>
<structfield>typtype</structfield> is <literal>b</literal> for
a basic type and <literal>c</literal> for a catalog type (i.e.,
a table). If <structfield>typtype</structfield> is
a base type and <literal>c</literal> for a complex type (i.e.,
a table's row type). If <structfield>typtype</structfield> is
<literal>c</literal>, <structfield>typrelid</structfield> is
the OID of the type's entry in
<structname>pg_class</structname>.
@ -1925,7 +2326,10 @@
<entry>typisdefined</entry>
<entry><type>bool</type></entry>
<entry></entry>
<entry>???</entry>
<entry>True if the type is defined, false if this is a placeholder
entry for a not-yet-defined type. When typisdefined is false,
nothing except the type name and OID can be relied on.
</entry>
</row>
<row>
@ -1940,7 +2344,7 @@
<entry><type>oid</type></entry>
<entry>pg_class.oid</entry>
<entry>
If this is a catalog type (see
If this is a complex type (see
<structfield>typtype</structfield>), then this field points to
the <structfield>pg_class</structfield> entry that defines the
corresponding table. A table could theoretically be used as a