database/postgres
1
0
Fork 0
mirror of https://github.com/postgres/postgres.git synced 2025-07-28 23:42:10 +03:00
Code Activity

I've created a new shared catalog table pg_shdescription to store

Browse Source 
comments on cluster global objects like databases, tablespaces, and
roles.

It touches a lot of places, but not much in the way of big changes.  The
only design decision I made was to duplicate the query and manipulation
functions rather than to try and have them handle both shared and local
comments.  I believe this is simpler for the code and not an issue for
callers because they know what type of object they are dealing with.
This has resulted in a shobj_description function analagous to
obj_description and backend functions [Create/Delete]SharedComments
mirroring the existing [Create/Delete]Comments functions.

pg_shdescription.h goes into src/include/catalog/

Kris Jurka
This commit is contained in:
Bruce Momjian
2006-02-12 03:22:21 +00:00
parent 95dbf9c02f
commit f9a726aa88
25 changed files with 617 additions and 82 deletions
Download Patch File Download Diff File Expand all files Collapse all files

80
doc/src/sgml/catalogs.sgml
View File

@ -1,6 +1,6 @@
<!--
Documentation of the system catalogs, directed toward PostgreSQL developers
$PostgreSQL: pgsql/doc/src/sgml/catalogs.sgml,v 2.119 2006/01/21 19:05:59 tgl Exp $
$PostgreSQL: pgsql/doc/src/sgml/catalogs.sgml,v 2.120 2006/02/12 03:22:16 momjian Exp $
-->
<chapter id="catalogs">
@ -188,6 +188,11 @@
<entry>dependencies on shared objects</entry>
</row>
<row>
<entry><link linkend="catalog-pg-shdescription"><structname>pg_shdescription</structname></link></entry>
<entry>comments on shared objects</entry>
</row>
<row>
<entry><link linkend="catalog-pg-statistic"><structname>pg_statistic</structname></link></entry>
<entry>planner statistics</entry>
@ -2230,6 +2235,12 @@
contents of <structname>pg_description</structname>.
</para>
<para>
See also <link linkend="catalog-pg-shdescription"><structname>pg_shdescription</structname></link>,
which performs a similar function for descriptions involving objects that
are shared across a database cluster.
</para>
<table>
<title><structname>pg_description</> Columns</title>
@ -3612,6 +3623,73 @@
</sect1>
<sect1 id="catalog-pg-shdescription">
<title><structname>pg_shdescription</structname></title>
<indexterm zone="catalog-pg-shdescription">
<primary>pg_shdescription</primary>
</indexterm>
<para>
The catalog <structname>pg_shdescription</structname> stores optional
descriptions (comments) for shared database objects. Descriptions can
be manipulated with the <command>COMMENT</command> command and viewed
with <application>psql</application>'s <literal>\d</literal> commands.
</para>
<para>
See also <link linkend="catalog-pg-description"><structname>pg_description</structname></link>,
which performs a similar function for descriptions involving objects
within a single database.
</para>
<para>
Unlike most system catalogs, <structname>pg_shdescription</structname>
is shared across all databases of a cluster: there is only one
copy of <structname>pg_shdescription</structname> per cluster, not
one per database.
</para>
<table>
<title><structname>pg_shdescription</> Columns</title>
<tgroup cols=4>
<thead>
<row>
<entry>Name</entry>
<entry>Type</entry>
<entry>References</entry>
<entry>Description</entry>
</row>
</thead>
<tbody>
<row>
<entry><structfield>objoid</structfield></entry>
<entry><type>oid</type></entry>
<entry>any OID column</entry>
<entry>The OID of the object this description pertains to</entry>
</row>
<row>
<entry><structfield>classoid</structfield></entry>
<entry><type>oid</type></entry>
<entry><literal><link linkend="catalog-pg-class"><structname>pg_class</structname></link>.oid</literal></entry>
<entry>The OID of the system catalog this object appears in</entry>
</row>
<row>
<entry><structfield>description</structfield></entry>
<entry><type>text</type></entry>
<entry></entry>
<entry>Arbitrary text that servers as the description of this object.</entry>
</row>
</tbody>
</tgroup>
</table>
</sect1>
<sect1 id="catalog-pg-statistic">
<title><structname>pg_statistic</structname></title>

19
doc/src/sgml/func.sgml
View File

@ -1,5 +1,5 @@
<!--
$PostgreSQL: pgsql/doc/src/sgml/func.sgml,v 1.304 2006/02/11 03:32:38 momjian Exp $
$PostgreSQL: pgsql/doc/src/sgml/func.sgml,v 1.305 2006/02/12 03:22:16 momjian Exp $
PostgreSQL documentation
-->
@ -9463,6 +9463,10 @@ SELECT pg_type_is_visible('myschema.widget'::regtype);
<primary>col_description</primary>
</indexterm>
<indexterm zone="functions-info">
<primary>shobj_description</primary>
</indexterm>
<indexterm zone="functions-info">
<primary>comment</primary>
<secondary sortas="database objects">about database objects</secondary>
@ -9499,6 +9503,11 @@ SELECT pg_type_is_visible('myschema.widget'::regtype);
<entry><type>text</type></entry>
<entry>get comment for a table column</entry>
</row>
<row>
<entry><literal><function>shobj_description</function>(<parameter>object_oid</parameter>, <parameter>catalog_name</parameter>)</literal></entry>
<entry><type>text</type></entry>
<entry>get comment for a shared database object</entry>
</row>
</tbody>
</tgroup>
</table>
@ -9521,6 +9530,14 @@ SELECT pg_type_is_visible('myschema.widget'::regtype);
<function>obj_description</function> cannot be used for table columns since
columns do not have OIDs of their own.
</para>
<para>
<function>shobj_description</function> is used just like
<function>obj_description</function> only that it is used for retrieving
comments on shared objects. Some system catalogs are global to all
databases within each cluster and their descriptions are stored globally
as well.
</para>
</sect1>
<sect1 id="functions-admin">

21
doc/src/sgml/ref/comment.sgml
View File

@ -1,5 +1,5 @@
<!--
$PostgreSQL: pgsql/doc/src/sgml/ref/comment.sgml,v 1.29 2005/06/08 21:15:27 tgl Exp $
$PostgreSQL: pgsql/doc/src/sgml/ref/comment.sgml,v 1.30 2006/02/12 03:22:17 momjian Exp $
PostgreSQL documentation
-->
@ -36,9 +36,11 @@ COMMENT ON
OPERATOR <replaceable class="PARAMETER">op</replaceable> (<replaceable class="PARAMETER">leftoperand_type</replaceable>, <replaceable class="PARAMETER">rightoperand_type</replaceable>) |
OPERATOR CLASS <replaceable class="PARAMETER">object_name</replaceable> USING <replaceable class="parameter">index_method</replaceable> |
[ PROCEDURAL ] LANGUAGE <replaceable class="PARAMETER">object_name</replaceable> |
ROLE <replaceable class="PARAMETER">object_name</replaceable> |
RULE <replaceable class="PARAMETER">rule_name</replaceable> ON <replaceable class="PARAMETER">table_name</replaceable> |
SCHEMA <replaceable class="PARAMETER">object_name</replaceable> |
SEQUENCE <replaceable class="PARAMETER">object_name</replaceable> |
TABLESPACE <replaceable class="PARAMETER">object_name</replaceable> |
TRIGGER <replaceable class="PARAMETER">trigger_name</replaceable> ON <replaceable class="PARAMETER">table_name</replaceable> |
TYPE <replaceable class="PARAMETER">object_name</replaceable> |
VIEW <replaceable class="PARAMETER">object_name</replaceable>
@ -67,7 +69,8 @@ COMMENT ON
<command>\dd</command>, <command>\d+</command>, and <command>\l+</command>.
Other user interfaces to retrieve comments can be built atop
the same built-in functions that <application>psql</application> uses, namely
<function>obj_description</> and <function>col_description</>
<function>obj_description</>, <function>col_description</>,
and <function>shobj_description</>
(see <xref linkend="functions-info-comment-table">).
</para>
</refsect1>
@ -197,17 +200,15 @@ COMMENT ON
<refsect1>
<title>Notes</title>
<para>
A comment for a database can only be created in that database,
and will only be visible in that database, not in other databases.
</para>
<para>
There is presently no security mechanism for comments: any user
connected to a database can see all the comments for objects in
that database (although only superusers can change comments for
objects that they don't own). Therefore, don't put
security-critical information in comments.
objects that they don't own). For shared objects such as
databases, roles, and tablespaces comments are stored gloablly
and any user connected to any database can see all the comments
for shared objects. Therefore, don't put security-critical
information in comments.
</para>
</refsect1>
@ -245,10 +246,12 @@ COMMENT ON LARGE OBJECT 346344 IS 'Planning document';
COMMENT ON OPERATOR ^ (text, text) IS 'Performs intersection of two texts';
COMMENT ON OPERATOR - (NONE, text) IS 'This is a prefix operator on text';
COMMENT ON OPERATOR CLASS int4ops USING btree IS '4 byte integer operators for btrees';
COMMENT ON ROLE my_role IS 'Administration group for finance tables';
COMMENT ON RULE my_rule ON my_table IS 'Logs updates of employee records';
COMMENT ON SCHEMA my_schema IS 'Departmental data';
COMMENT ON SEQUENCE my_sequence IS 'Used to generate primary keys';
COMMENT ON TABLE my_schema.my_table IS 'Employee Information';
COMMENT ON TABLESPACE my_tablespace IS 'Tablespace for indexes';
COMMENT ON TRIGGER my_trigger ON my_table IS 'Used for RI';
COMMENT ON TYPE complex IS 'Complex number data type';
COMMENT ON VIEW my_view IS 'View of departmental costs';