Skip to content

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

Add note about pg_stats to pg_statistic entry; add sections for 

pg_largeobject, pg_listener, pg_rewrite, pg_trigger; miscellaneous
small improvements.
parent e158670c
Show whitespace changes
Inline Side-by-side
Showing with 432 additions and 28 deletions
doc/src/sgml/catalogs.sgml
View file @ daf72bba
<!-- <!--
Documentation of the system catalogs, directed toward PostgreSQL developers 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"> <chapter id="catalogs">
...@@ -63,7 +63,7 @@ ...@@ -63,7 +63,7 @@
<row> <row>
<entry>pg_attribute</entry> <entry>pg_attribute</entry>
<entry>table columns (attributes, fields)</entry> <entry>table columns (<quote>attributes</quote>, <quote>fields</quote>)</entry>
</row> </row>
<row> <row>
...@@ -73,7 +73,7 @@ ...@@ -73,7 +73,7 @@
<row> <row>
<entry>pg_database</entry> <entry>pg_database</entry>
<entry>databases</entry> <entry>databases within this database cluster</entry>
</row> </row>
<row> <row>
...@@ -83,7 +83,7 @@ ...@@ -83,7 +83,7 @@
<row> <row>
<entry>pg_group</entry> <entry>pg_group</entry>
<entry>user groups</entry> <entry>groups of database users</entry>
</row> </row>
<row> <row>
...@@ -162,8 +162,7 @@ ...@@ -162,8 +162,7 @@
<para> <para>
More detailed documentation of most catalogs follow below. The More detailed documentation of most catalogs follow below. The
catalogs that relate to index access methods are explained in the catalogs that relate to index access methods are explained in the
<citetitle>Programmer's Guide</citetitle>. Some catalogs don't <citetitle>Programmer's Guide</citetitle>.
have any documentation, yet.
</para> </para>
</section> </section>
...@@ -210,13 +209,13 @@ ...@@ -210,13 +209,13 @@
<row> <row>
<entry>aggtransfn</entry> <entry>aggtransfn</entry>
<entry><type>regproc</type> (function)</entry> <entry><type>regproc</type> (function)</entry>
<entry></entry> <entry>pg_proc.oid</entry>
<entry>Transition function</entry> <entry>Transition function</entry>
</row> </row>
<row> <row>
<entry>aggfinalfn</entry> <entry>aggfinalfn</entry>
<entry><type>regproc</type> (function)</entry> <entry><type>regproc</type> (function)</entry>
<entry></entry> <entry>pg_proc.oid</entry>
<entry>Final function</entry> <entry>Final function</entry>
</row> </row>
<row> <row>
...@@ -431,7 +430,7 @@ ...@@ -431,7 +430,7 @@
<entry></entry> <entry></entry>
<entry> <entry>
Always -1 in storage, but when loaded into a tuple descriptor 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. within the tuple.
</entry> </entry>
</row> </row>
...@@ -653,7 +652,8 @@ ...@@ -653,7 +652,8 @@
<entry><type>bool</type></entry> <entry><type>bool</type></entry>
<entry></entry> <entry></entry>
<entry>True if this table is shared across all databases in the <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>
<row> <row>
...@@ -741,7 +741,9 @@ ...@@ -741,7 +741,9 @@
<entry>relhasrules</entry> <entry>relhasrules</entry>
<entry><type>bool</type></entry> <entry><type>bool</type></entry>
<entry></entry> <entry></entry>
<entry>Table has rules</entry> <entry>Table has rules; see
<structname>pg_rewrite</structname> catalog
</entry>
</row> </row>
<row> <row>
...@@ -772,14 +774,19 @@ ...@@ -772,14 +774,19 @@
<para> <para>
The <structname>pg_database</structname> catalog stores information The <structname>pg_database</structname> catalog stores information
about the available databases. The about the available databases. Databases are created with the
<structname>pg_database</structname> table is shared between all <command>CREATE DATABASE</command> command. Consult the
databases of a cluster. Databases are created with the
<command>CREATE DATABASE</command>. Consult the
<citetitle>Administrator's Guide</citetitle> for details about the <citetitle>Administrator's Guide</citetitle> for details about the
meaning of some of the parameters. meaning of some of the parameters.
</para> </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> <table>
<title>pg_database Columns</title> <title>pg_database Columns</title>
...@@ -959,6 +966,14 @@ ...@@ -959,6 +966,14 @@
Guide</citetitle> for information about user permission management. Guide</citetitle> for information about user permission management.
</para> </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> <table>
<title>pg_group Columns</title> <title>pg_group Columns</title>
...@@ -1039,7 +1054,7 @@ ...@@ -1039,7 +1054,7 @@
<row> <row>
<entry>indproc</entry> <entry>indproc</entry>
<entry><type>oid</type></entry> <entry><type>regproc</type></entry>
<entry>pg_proc.oid</entry> <entry>pg_proc.oid</entry>
<entry>The registered procedure if this is a functional index</entry> <entry>The registered procedure if this is a functional index</entry>
</row> </row>
...@@ -1086,7 +1101,8 @@ ...@@ -1086,7 +1101,8 @@
<entry>indisprimary</entry> <entry>indisprimary</entry>
<entry><type>bool</type></entry> <entry><type>bool</type></entry>
<entry></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>
<row> <row>
...@@ -1147,7 +1163,7 @@ ...@@ -1147,7 +1163,7 @@
<entry><type>oid</type></entry> <entry><type>oid</type></entry>
<entry>pg_class.oid</entry> <entry>pg_class.oid</entry>
<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 referenced by <structfield>inhrelid</structfield> inherited
from. from.
</entry> </entry>
...@@ -1158,7 +1174,7 @@ ...@@ -1158,7 +1174,7 @@
<entry><type>int4</type></entry> <entry><type>int4</type></entry>
<entry></entry> <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 inheritance), this number tells the order in which the
inherited columns are to be arranged. The count starts at 1. inherited columns are to be arranged. The count starts at 1.
</entry> </entry>
...@@ -1250,6 +1266,132 @@ ...@@ -1250,6 +1266,132 @@
</section> </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"> <section id="catalog-pg-operator">
<title>pg_operator</title> <title>pg_operator</title>
...@@ -1489,7 +1631,8 @@ ...@@ -1489,7 +1631,8 @@
<entry>proretset</entry> <entry>proretset</entry>
<entry><type>bool</type></entry> <entry><type>bool</type></entry>
<entry></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>
<row> <row>
...@@ -1542,7 +1685,7 @@ ...@@ -1542,7 +1685,7 @@
This tells the function handler how to invoke the function. It This tells the function handler how to invoke the function. It
might be the actual source code of the function for interpreted might be the actual source code of the function for interpreted
languages, a link symbol, a file name, or just about anything 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> </entry>
</row> </row>
...@@ -1550,12 +1693,26 @@ ...@@ -1550,12 +1693,26 @@
<entry>probin</entry> <entry>probin</entry>
<entry><type>bytea</type></entry> <entry><type>bytea</type></entry>
<entry></entry> <entry></entry>
<entry>?</entry> <entry>Additional information about how to invoke the function.
Again, the interpretation is language-specific.
</entry>
</row> </row>
</tbody> </tbody>
</tgroup> </tgroup>
</table> </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> </section>
...@@ -1608,7 +1765,7 @@ ...@@ -1608,7 +1765,7 @@
<entry>rcsrc</entry> <entry>rcsrc</entry>
<entry><type>text</type></entry> <entry><type>text</type></entry>
<entry></entry> <entry></entry>
<entry>A human-readable representation of the consraint expression</entry> <entry>A human-readable representation of the constraint expression</entry>
</row> </row>
</tbody> </tbody>
</tgroup> </tgroup>
...@@ -1624,6 +1781,93 @@ ...@@ -1624,6 +1781,93 @@
</section> </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"> <section id="catalog-pg-shadow">
<title>pg_shadow</title> <title>pg_shadow</title>
...@@ -1631,7 +1875,7 @@ ...@@ -1631,7 +1875,7 @@
<structname>pg_shadow</structname> contains information about <structname>pg_shadow</structname> contains information about
database users. The name stems from the fact that this table database users. The name stems from the fact that this table
should not be readable by the public since it contains passwords. 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. <structname>pg_shadow</structname> that blanks out the password field.
</para> </para>
...@@ -1640,6 +1884,14 @@ ...@@ -1640,6 +1884,14 @@
information about user and permission management. information about user and permission management.
</para> </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> <table>
<title>pg_shadow Columns</title> <title>pg_shadow Columns</title>
...@@ -1743,6 +1995,20 @@ ...@@ -1743,6 +1995,20 @@
<filename>src/include/catalog/pg_statistic.h</filename>. <filename>src/include/catalog/pg_statistic.h</filename>.
</para> </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> <table>
<title>pg_statistic Columns</title> <title>pg_statistic Columns</title>
...@@ -1843,9 +2109,144 @@ ...@@ -1843,9 +2109,144 @@
</section> </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"> <section id="catalog-pg-type">
<title>pg_type</title> <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> <table>
<title>pg_type Columns</title> <title>pg_type Columns</title>
...@@ -1913,8 +2314,8 @@ ...@@ -1913,8 +2314,8 @@
<entry></entry> <entry></entry>
<entry> <entry>
<structfield>typtype</structfield> is <literal>b</literal> for <structfield>typtype</structfield> is <literal>b</literal> for
a basic type and <literal>c</literal> for a catalog type (i.e., a base type and <literal>c</literal> for a complex type (i.e.,
a table). If <structfield>typtype</structfield> is a table's row type). If <structfield>typtype</structfield> is
<literal>c</literal>, <structfield>typrelid</structfield> is <literal>c</literal>, <structfield>typrelid</structfield> is
the OID of the type's entry in the OID of the type's entry in
<structname>pg_class</structname>. <structname>pg_class</structname>.
...@@ -1925,7 +2326,10 @@ ...@@ -1925,7 +2326,10 @@
<entry>typisdefined</entry> <entry>typisdefined</entry>
<entry><type>bool</type></entry> <entry><type>bool</type></entry>
<entry></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>
<row> <row>
...@@ -1940,7 +2344,7 @@ ...@@ -1940,7 +2344,7 @@
<entry><type>oid</type></entry> <entry><type>oid</type></entry>
<entry>pg_class.oid</entry> <entry>pg_class.oid</entry>
<entry> <entry>
If this is a catalog type (see If this is a complex type (see
<structfield>typtype</structfield>), then this field points to <structfield>typtype</structfield>), then this field points to
the <structfield>pg_class</structfield> entry that defines the the <structfield>pg_class</structfield> entry that defines the
corresponding table. A table could theoretically be used as a corresponding table. A table could theoretically be used as a
......
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