Document obj_description and col_description functions; expand
description of COMMENT command.
This commit is contained in:
Tom Lane
parent
44d1e9d552
commit
9935a85fa4
|
|
@ -1,5 +1,5 @@
|
|||
<!--
|
||||
$Header: /cvsroot/pgsql/doc/src/sgml/func.sgml,v 1.88 2001/12/23 20:22:49 tgl Exp $
|
||||
$Header: /cvsroot/pgsql/doc/src/sgml/func.sgml,v 1.89 2001/12/27 21:36:57 tgl Exp $
|
||||
PostgreSQL documentation
|
||||
-->
|
||||
|
||||
|
|
@ -2643,7 +2643,7 @@ PostgreSQL documentation
|
|||
<row>
|
||||
<entry><function>current_timestamp</function></entry>
|
||||
<entry><type>timestamp</type></entry>
|
||||
<entry>date and time; see also <link
|
||||
<entry>Date and time; see <link
|
||||
linkend="functions-datetime-current">below</link>
|
||||
</entry>
|
||||
<entry></entry>
|
||||
|
|
@ -2722,7 +2722,7 @@ PostgreSQL documentation
|
|||
<entry><function>now</function>()</entry>
|
||||
<entry><type>timestamp</type></entry>
|
||||
<entry>Current date and time (equivalent to
|
||||
<function>current_timestamp</function>); see also <link
|
||||
<function>current_timestamp</function>); see <link
|
||||
linkend="functions-datetime-current">below</link>
|
||||
</entry>
|
||||
<entry></entry>
|
||||
|
|
@ -4399,6 +4399,66 @@ SELECT NULLIF(value, '(none)') ...
|
|||
<structfield>usesysid</> value.
|
||||
</para>
|
||||
|
||||
<table>
|
||||
<title>Comment Information Functions</>
|
||||
<tgroup cols="3">
|
||||
<thead>
|
||||
<row><entry>Name</> <entry>Return Type</> <entry>Description</></row>
|
||||
</thead>
|
||||
|
||||
<tbody>
|
||||
<row>
|
||||
<entry><function>obj_description</>(<parameter>objectOID</parameter>, <parameter>tablename</>)</entry>
|
||||
<entry><type>text</></entry>
|
||||
<entry>Get comment for a database object</>
|
||||
</row>
|
||||
<row>
|
||||
<entry><function>obj_description</>(<parameter>objectOID</parameter>)</entry>
|
||||
<entry><type>text</></entry>
|
||||
<entry>Get comment for a database object (<emphasis>deprecated</>)</entry>
|
||||
</row>
|
||||
<row>
|
||||
<entry><function>col_description</>(<parameter>tableOID</parameter>, <parameter>columnnumber</>)</entry>
|
||||
<entry><type>text</></entry>
|
||||
<entry>Get comment for a table column</>
|
||||
</row>
|
||||
</tbody>
|
||||
</tgroup>
|
||||
</table>
|
||||
|
||||
<indexterm zone="functions-misc">
|
||||
<primary>obj_description</primary>
|
||||
</indexterm>
|
||||
|
||||
<indexterm zone="functions-misc">
|
||||
<primary>col_description</primary>
|
||||
</indexterm>
|
||||
|
||||
<para>
|
||||
These functions extract comments previously stored with the
|
||||
<command>COMMENT</> command. <literal>NULL</> is returned if
|
||||
no comment can be found matching the specified parameters.
|
||||
</para>
|
||||
|
||||
<para>
|
||||
The two-parameter form of <function>obj_description()</> returns the
|
||||
comment for a database object specified by its OID and the name of the
|
||||
containing system catalog. For example,
|
||||
<literal>obj_description(123456,'pg_class')</>
|
||||
would retrieve the comment for a table with OID 123456.
|
||||
The one-parameter form of <function>obj_description()</> requires only
|
||||
the object OID. It is now deprecated since there is no guarantee that
|
||||
OIDs are unique across different system catalogs; therefore, the wrong
|
||||
comment could be returned.
|
||||
</para>
|
||||
|
||||
<para>
|
||||
<function>col_description()</> returns the comment for a table column,
|
||||
which is specified by the OID of its table and its column number.
|
||||
<function>obj_description()</> cannot be used for table columns since
|
||||
columns do not have OIDs of their own.
|
||||
</para>
|
||||
|
||||
</sect1>
|
||||
|
||||
|
||||
|
|
|
|||
|
|
@ -1,5 +1,5 @@
|
|||
<!--
|
||||
$Header: /cvsroot/pgsql/doc/src/sgml/ref/comment.sgml,v 1.11 2001/12/08 03:24:34 thomas Exp $
|
||||
$Header: /cvsroot/pgsql/doc/src/sgml/ref/comment.sgml,v 1.12 2001/12/27 21:36:57 tgl Exp $
|
||||
PostgreSQL documentation
|
||||
-->
|
||||
|
||||
|
|
@ -98,12 +98,30 @@ COMMENT
|
|||
Description
|
||||
</title>
|
||||
<para>
|
||||
<command>COMMENT</command> adds a comment to an object that can be
|
||||
<command>COMMENT</command> stores a comment about a database object.
|
||||
Comments can be
|
||||
easily retrieved with <command>psql</command>'s
|
||||
<command>\dd</command>, <command>\d+</command>, or <command>\l+</command> commands.
|
||||
To remove a comment, write <literal>NULL</literal>.
|
||||
<command>\dd</command>, <command>\d+</command>, or <command>\l+</command>
|
||||
commands. Other user interfaces to retrieve comments can be built atop
|
||||
the same built-in functions that <command>psql</command> uses, namely
|
||||
<function>obj_description()</> and <function>col_description()</>.
|
||||
</para>
|
||||
|
||||
<para>
|
||||
To modify a comment, issue a new <command>COMMENT</> command for the
|
||||
same object. Only one comment string is stored for each object.
|
||||
To remove a comment, write <literal>NULL</literal> in place of the text
|
||||
string.
|
||||
Comments are automatically dropped when the object is dropped.
|
||||
</para>
|
||||
|
||||
<para>
|
||||
It should be noted that 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.
|
||||
</para>
|
||||
</refsect1>
|
||||
|
||||
<refsect1 id="R1-SQL-COMMENT-2">
|
||||
|
|
|
|||
Loading…
Reference in New Issue