~ubuntu-branches/ubuntu/quantal/postgresql-9.1/quantal-proposed

« back to all changes in this revision

Viewing changes to doc/src/sgml/man7/COMMENT.7

  • Committer: Package Import Robot
  • Author(s): Martin Pitt
  • Date: 2011-12-02 14:39:18 UTC
  • mfrom: (12.1.1 sid)
  • Revision ID: package-import@ubuntu.com-20111202143918-1ftj0oo87w0y8m8d
* New upstream bug fix release:
  - Fix bugs in information_schema.referential_constraints view.
    This view was being insufficiently careful about matching the
    foreign-key constraint to the depended-on primary or unique key
    constraint. That could result in failure to show a foreign key
    constraint at all, or showing it multiple times, or claiming that
    it depends on a different constraint than the one it really does.
    Since the view definition is installed by initdb, merely upgrading
    will not fix the problem. If you need to fix this in an existing
    installation, you can (as a superuser) drop the information_schema
    schema then re-create it by sourcing
    "SHAREDIR/information_schema.sql". (Run pg_config --sharedir if
    you're uncertain where "SHAREDIR" is.) This must be repeated in
    each database to be fixed.
  - Make "contrib/citext"'s upgrade script fix collations of citext
    columns and indexes.
    Existing citext columns and indexes aren't correctly marked as
    being of a collatable data type during pg_upgrade from a pre-9.1
    server. That leads to operations on them failing with errors such
    as "could not determine which collation to use for string
    comparison". This change allows them to be fixed by the same script
    that upgrades the citext module into a proper 9.1 extension during
    CREATE EXTENSION citext FROM unpackaged.
    If you have a previously-upgraded database that is suffering from
    this problem, and you already ran the "CREATE EXTENSION" command,
    you can manually run (as superuser) the "UPDATE" commands found at
    the end of "SHAREDIR/extension/citext--unpackaged--1.0.sql". (Run
    pg_config --sharedir if you're uncertain where "SHAREDIR" is.)
  - Fix possible crash during "UPDATE" or "DELETE" that joins to the
    output of a scalar-returning function.
  - Fix incorrect replay of WAL records for GIN index updates.
  - Fix TOAST-related data corruption during CREATE TABLE dest AS
    SELECT - FROM src or INSERT INTO dest SELECT * FROM src.
  - Fix possible failures during hot standby startup.
  - Start hot standby faster when initial snapshot is incomplete.
  - Fix race condition during toast table access from stale syscache
    entries. The typical symptom was transient errors like "missing chunk
    number 0 for toast value NNNNN in pg_toast_2619", where the cited toast
    table would always belong to a system catalog.
  - Track dependencies of functions on items used in parameter default
    expressions. Previously, a referenced object could be dropped without
    having dropped or modified the function, leading to misbehavior when
    the function was used. Note that merely installing this update will not
    fix the missing dependency entries; to do that, you'd need to
    "CREATE OR REPLACE" each such function afterwards. If you have
    functions whose defaults depend on non-built-in objects, doing so
    is recommended.
  - Fix incorrect management of placeholder variables in nestloop joins.
    This bug is known to lead to "variable not found in subplan target
    list" planner errors, and could possibly result in wrong query
    output when outer joins are involved.
  - Fix window functions that sort by expressions involving aggregates.
  - Fix "MergeAppend child's targetlist doesn't match MergeAppend"
    planner errors.
  - Fix index matching for operators with both collatable and
    noncollatable inputs. In 9.1.0, an indexable operator that has a
    non-collatable left-hand input type and a collatable right-hand input
    type would not be recognized as matching the left-hand column's index.
    An example is the hstore ? text operator.
  - Allow inlining of set-returning SQL functions with multiple OUT
    parameters.
  - Don't trust deferred-unique indexes for join removal.
  - Make DatumGetInetP() unpack inet datums that have a 1-byte header,
    and add a new macro, DatumGetInetPP(), that does not.
  - Improve locale support in money type's input and output.
    Aside from not supporting all standard lc_monetary formatting
    options, the input and output functions were inconsistent, meaning
    there were locales in which dumped money values could not be
    re-read.
  - Don't let transform_null_equals affect CASE foo WHEN NULL ...
    constructs.  transform_null_equals is only supposed to affect foo =
    NULL expressions written directly by the user, not equality checks
    generated internally by this form of CASE.
  - Change foreign-key trigger creation order to better support
    self-referential foreign keys.
  - Fix IF EXISTS to work correctly in "DROP OPERATOR FAMILY".
  - Disallow dropping of an extension from within its own script.
  - Don't mark auto-generated types as extension members.
  - Cope with invalid pre-existing search_path settings during "CREATE
    EXTENSION".
  - Avoid floating-point underflow while tracking buffer allocation
    rate.
  - Prevent autovacuum transactions from running in serializable mode.
    Autovacuum formerly used the cluster-wide default transaction
    isolation level, but there is no need for it to use anything higher
    than READ COMMITTED, and using SERIALIZABLE could result in
    unnecessary delays for other processes.
  - Ensure walsender processes respond promptly to SIGTERM.
  - Exclude "postmaster.opts" from base backups.
  - Fix incorrect field alignment in ecpg's SQLDA area.
  - Preserve blank lines within commands in psql's command history.
    The former behavior could cause problems if an empty line was
    removed from within a string literal, for example.
  - Avoid platform-specific infinite loop in pg_dump.
  - Fix compression of plain-text output format in pg_dump.
    pg_dump has historically understood -Z with no -F switch to mean
    that it should emit a gzip-compressed version of its plain text
    output. Restore that behavior.
  - Fix pg_dump to dump user-defined casts between auto-generated
    types, such as table rowtypes.
  - Fix missed quoting of foreign server names in pg_dump.
  - Assorted fixes for pg_upgrade. Handle exclusion constraints correctly,
    avoid failures on Windows, don't complain about mismatched toast table
    names in 8.4 databases.
  - In PL/pgSQL, allow foreign tables to define row types.
  - Fix up conversions of PL/Perl functions' results.
    Restore the pre-9.1 behavior that PL/Perl functions returning void
    ignore the result value of their last Perl statement; 9.1.0 would
    throw an error if that statement returned a reference. Also, make
    sure it works to return a string value for a composite type, so
    long as the string meets the type's input format. In addition,
    throw errors for attempts to return Perl arrays or hashes when the
    function's declared result type is not an array or composite type,
    respectively. (Pre-9.1 versions rather uselessly returned strings
    like ARRAY(0x221a9a0) or HASH(0x221aa90) in such cases.)
  - Ensure PL/Perl strings are always correctly UTF8-encoded.
  - Use the preferred version of xsubpp to build PL/Perl, not
    necessarily the operating system's main copy.
  - Correctly propagate SQLSTATE in PL/Python exceptions.
  - Do not install PL/Python extension files for Python major versions
    other than the one built against.
  - Change all the "contrib" extension script files to report a useful
    error message if they are fed to psql. This should help teach people
    about the new method of using "CREATE EXTENSION" to load these files.
    In most cases, sourcing the scripts directly would fail anyway, but
    with harder-to-interpret messages.
  - Fix incorrect coding in "contrib/dict_int" and "contrib/dict_xsyn".
  - Remove "contrib/sepgsql" tests from the regular regression test
    mechanism. Since these tests require root privileges for setup, they're
    impractical to run automatically. Switch over to a manual approach
    instead, and provide a testing script to help with that.
  - Fix assorted errors in "contrib/unaccent"'s configuration file
    parsing.
  - Honor query cancel interrupts promptly in pgstatindex().
  - Revert unintentional enabling of WAL_DEBUG. Fortunately, as debugging
    tools go, this one is pretty cheap; but it's not intended to be enabled
    by default, so revert.
  - Ensure VPATH builds properly install all server header files.
  - Shorten file names reported in verbose error messages.
    Regular builds have always reported just the name of the C file
    containing the error message call, but VPATH builds formerly
    reported an absolute path name.
* debian/rules: Fix build failure for binary-indep-only builds.
  (Closes: #646079)

Show diffs side-by-side

added added

removed removed

Lines of Context:
1
1
'\" t
2
2
.\"     Title: COMMENT
3
3
.\"    Author: The PostgreSQL Global Development Group
4
 
.\" Generator: DocBook XSL Stylesheets v1.75.1 <http://docbook.sf.net/>
5
 
.\"      Date: 2011-09-22
6
 
.\"    Manual: PostgreSQL 9.1.1 Documentation
7
 
.\"    Source: PostgreSQL 9.1.1
 
4
.\" Generator: DocBook XSL Stylesheets v1.75.2 <http://docbook.sf.net/>
 
5
.\"      Date: 2011-12-01
 
6
.\"    Manual: PostgreSQL 9.1.2 Documentation
 
7
.\"    Source: PostgreSQL 9.1.2
8
8
.\"  Language: English
9
9
.\"
10
 
.TH "COMMENT" "7" "2011-09-22" "PostgreSQL 9.1.1" "PostgreSQL 9.1.1 Documentation"
 
10
.TH "COMMENT" "7" "2011-12-01" "PostgreSQL 9.1.2" "PostgreSQL 9.1.2 Documentation"
 
11
.\" -----------------------------------------------------------------
 
12
.\" * Define some portability stuff
 
13
.\" -----------------------------------------------------------------
 
14
.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
15
.\" http://bugs.debian.org/507673
 
16
.\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html
 
17
.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
18
.ie \n(.g .ds Aq \(aq
 
19
.el       .ds Aq '
11
20
.\" -----------------------------------------------------------------
12
21
.\" * set default formatting
13
22
.\" -----------------------------------------------------------------
58
67
  TRIGGER \fItrigger_name\fR ON \fItable_name\fR |
59
68
  TYPE \fIobject_name\fR |
60
69
  VIEW \fIobject_name\fR
61
 
} IS \(aq\fItext\fR\(aq
 
70
} IS \*(Aq\fItext\fR\*(Aq
62
71
.fi
63
72
.SH "DESCRIPTION"
64
73
.PP
72
81
NULL
73
82
in place of the text string\&. Comments are automatically dropped when their object is dropped\&.
74
83
.PP
75
 
For most kinds of object, only the object\(aqs owner can set the comment\&. Roles don\(aqt have owners, so the rule for
 
84
For most kinds of object, only the object\*(Aqs owner can set the comment\&. Roles don\*(Aqt have owners, so the rule for
76
85
COMMENT ON ROLE
77
86
is that you must be superuser to comment on a superuser role, or have the
78
87
CREATEROLE
79
88
privilege to comment on non\-superuser roles\&. Of course, a superuser can comment on anything\&.
80
89
.PP
81
90
Comments can be viewed using
82
 
psql\(aqs
 
91
psql\*(Aqs
83
92
\ed
84
93
family of commands\&. Other user interfaces to retrieve comments can be built atop the same built\-in functions that
85
94
psql
126
135
COMMENT ON FUNCTION
127
136
does not actually pay any attention to
128
137
OUT
129
 
arguments, since only the input arguments are needed to determine the function\(aqs identity\&. So it is sufficient to list the
 
138
arguments, since only the input arguments are needed to determine the function\*(Aqs identity\&. So it is sufficient to list the
130
139
IN,
131
140
INOUT, and
132
141
VARIADIC
137
146
.RS 4
138
147
The name of a function argument\&. Note that
139
148
COMMENT ON FUNCTION
140
 
does not actually pay any attention to argument names, since only the argument data types are needed to determine the function\(aqs identity\&.
 
149
does not actually pay any attention to argument names, since only the argument data types are needed to determine the function\*(Aqs identity\&.
141
150
.RE
142
151
.PP
143
152
\fIargtype\fR
144
153
.RS 4
145
 
The data type(s) of the function\(aqs arguments (optionally schema\-qualified), if any\&.
 
154
The data type(s) of the function\*(Aqs arguments (optionally schema\-qualified), if any\&.
146
155
.RE
147
156
.PP
148
157
\fIlarge_object_oid\fR
152
161
.PP
153
162
\fIleft_type\fR, \fIright_type\fR
154
163
.RS 4
155
 
The data type(s) of the operator\(aqs arguments (optionally schema\-qualified)\&. Write
 
164
The data type(s) of the operator\*(Aqs arguments (optionally schema\-qualified)\&. Write
156
165
NONE
157
166
for the missing argument of a prefix or postfix operator\&.
158
167
.RE
170
179
.RE
171
180
.SH "NOTES"
172
181
.PP
173
 
There is presently no security mechanism for viewing comments: any user connected to a database can see all the comments for objects in that database\&. For shared objects such as databases, roles, and tablespaces, comments are stored globally so any user connected to any database in the cluster can see all the comments for shared objects\&. Therefore, don\(aqt put security\-critical information in comments\&.
 
182
There is presently no security mechanism for viewing comments: any user connected to a database can see all the comments for objects in that database\&. For shared objects such as databases, roles, and tablespaces, comments are stored globally so any user connected to any database in the cluster can see all the comments for shared objects\&. Therefore, don\*(Aqt put security\-critical information in comments\&.
174
183
.SH "EXAMPLES"
175
184
.PP
176
185
Attach a comment to the table
180
189
.RS 4
181
190
.\}
182
191
.nf
183
 
COMMENT ON TABLE mytable IS \(aqThis is my table\&.\(aq;
 
192
COMMENT ON TABLE mytable IS \*(AqThis is my table\&.\*(Aq;
184
193
.fi
185
194
.if n \{\
186
195
.RE
204
213
.RS 4
205
214
.\}
206
215
.nf
207
 
COMMENT ON AGGREGATE my_aggregate (double precision) IS \(aqComputes sample variance\(aq;
208
 
COMMENT ON CAST (text AS int4) IS \(aqAllow casts from text to int4\(aq;
209
 
COMMENT ON COLLATION "fr_CA" IS \(aqCanadian French\(aq;
210
 
COMMENT ON COLUMN my_table\&.my_column IS \(aqEmployee ID number\(aq;
211
 
COMMENT ON CONVERSION my_conv IS \(aqConversion to UTF8\(aq;
212
 
COMMENT ON CONSTRAINT bar_col_cons ON bar IS \(aqConstrains column col\(aq;
213
 
COMMENT ON DATABASE my_database IS \(aqDevelopment Database\(aq;
214
 
COMMENT ON DOMAIN my_domain IS \(aqEmail Address Domain\(aq;
215
 
COMMENT ON EXTENSION hstore IS \(aqimplements the hstore data type\(aq;
216
 
COMMENT ON FOREIGN DATA WRAPPER mywrapper IS \(aqmy foreign data wrapper\(aq;
217
 
COMMENT ON FOREIGN TABLE my_foreign_table IS \(aqEmployee Information in other database\(aq;
218
 
COMMENT ON FUNCTION my_function (timestamp) IS \(aqReturns Roman Numeral\(aq;
219
 
COMMENT ON INDEX my_index IS \(aqEnforces uniqueness on employee ID\(aq;
220
 
COMMENT ON LANGUAGE plpython IS \(aqPython support for stored procedures\(aq;
221
 
COMMENT ON LARGE OBJECT 346344 IS \(aqPlanning document\(aq;
222
 
COMMENT ON OPERATOR ^ (text, text) IS \(aqPerforms intersection of two texts\(aq;
223
 
COMMENT ON OPERATOR \- (NONE, integer) IS \(aqUnary minus\(aq;
224
 
COMMENT ON OPERATOR CLASS int4ops USING btree IS \(aq4 byte integer operators for btrees\(aq;
225
 
COMMENT ON OPERATOR FAMILY integer_ops USING btree IS \(aqall integer operators for btrees\(aq;
226
 
COMMENT ON ROLE my_role IS \(aqAdministration group for finance tables\(aq;
227
 
COMMENT ON RULE my_rule ON my_table IS \(aqLogs updates of employee records\(aq;
228
 
COMMENT ON SCHEMA my_schema IS \(aqDepartmental data\(aq;
229
 
COMMENT ON SEQUENCE my_sequence IS \(aqUsed to generate primary keys\(aq;
230
 
COMMENT ON SERVER myserver IS \(aqmy foreign server\(aq;
231
 
COMMENT ON TABLE my_schema\&.my_table IS \(aqEmployee Information\(aq;
232
 
COMMENT ON TABLESPACE my_tablespace IS \(aqTablespace for indexes\(aq;
233
 
COMMENT ON TEXT SEARCH CONFIGURATION my_config IS \(aqSpecial word filtering\(aq;
234
 
COMMENT ON TEXT SEARCH DICTIONARY swedish IS \(aqSnowball stemmer for swedish language\(aq;
235
 
COMMENT ON TEXT SEARCH PARSER my_parser IS \(aqSplits text into words\(aq;
236
 
COMMENT ON TEXT SEARCH TEMPLATE snowball IS \(aqSnowball stemmer\(aq;
237
 
COMMENT ON TRIGGER my_trigger ON my_table IS \(aqUsed for RI\(aq;
238
 
COMMENT ON TYPE complex IS \(aqComplex number data type\(aq;
239
 
COMMENT ON VIEW my_view IS \(aqView of departmental costs\(aq;
 
216
COMMENT ON AGGREGATE my_aggregate (double precision) IS \*(AqComputes sample variance\*(Aq;
 
217
COMMENT ON CAST (text AS int4) IS \*(AqAllow casts from text to int4\*(Aq;
 
218
COMMENT ON COLLATION "fr_CA" IS \*(AqCanadian French\*(Aq;
 
219
COMMENT ON COLUMN my_table\&.my_column IS \*(AqEmployee ID number\*(Aq;
 
220
COMMENT ON CONVERSION my_conv IS \*(AqConversion to UTF8\*(Aq;
 
221
COMMENT ON CONSTRAINT bar_col_cons ON bar IS \*(AqConstrains column col\*(Aq;
 
222
COMMENT ON DATABASE my_database IS \*(AqDevelopment Database\*(Aq;
 
223
COMMENT ON DOMAIN my_domain IS \*(AqEmail Address Domain\*(Aq;
 
224
COMMENT ON EXTENSION hstore IS \*(Aqimplements the hstore data type\*(Aq;
 
225
COMMENT ON FOREIGN DATA WRAPPER mywrapper IS \*(Aqmy foreign data wrapper\*(Aq;
 
226
COMMENT ON FOREIGN TABLE my_foreign_table IS \*(AqEmployee Information in other database\*(Aq;
 
227
COMMENT ON FUNCTION my_function (timestamp) IS \*(AqReturns Roman Numeral\*(Aq;
 
228
COMMENT ON INDEX my_index IS \*(AqEnforces uniqueness on employee ID\*(Aq;
 
229
COMMENT ON LANGUAGE plpython IS \*(AqPython support for stored procedures\*(Aq;
 
230
COMMENT ON LARGE OBJECT 346344 IS \*(AqPlanning document\*(Aq;
 
231
COMMENT ON OPERATOR ^ (text, text) IS \*(AqPerforms intersection of two texts\*(Aq;
 
232
COMMENT ON OPERATOR \- (NONE, integer) IS \*(AqUnary minus\*(Aq;
 
233
COMMENT ON OPERATOR CLASS int4ops USING btree IS \*(Aq4 byte integer operators for btrees\*(Aq;
 
234
COMMENT ON OPERATOR FAMILY integer_ops USING btree IS \*(Aqall integer operators for btrees\*(Aq;
 
235
COMMENT ON ROLE my_role IS \*(AqAdministration group for finance tables\*(Aq;
 
236
COMMENT ON RULE my_rule ON my_table IS \*(AqLogs updates of employee records\*(Aq;
 
237
COMMENT ON SCHEMA my_schema IS \*(AqDepartmental data\*(Aq;
 
238
COMMENT ON SEQUENCE my_sequence IS \*(AqUsed to generate primary keys\*(Aq;
 
239
COMMENT ON SERVER myserver IS \*(Aqmy foreign server\*(Aq;
 
240
COMMENT ON TABLE my_schema\&.my_table IS \*(AqEmployee Information\*(Aq;
 
241
COMMENT ON TABLESPACE my_tablespace IS \*(AqTablespace for indexes\*(Aq;
 
242
COMMENT ON TEXT SEARCH CONFIGURATION my_config IS \*(AqSpecial word filtering\*(Aq;
 
243
COMMENT ON TEXT SEARCH DICTIONARY swedish IS \*(AqSnowball stemmer for swedish language\*(Aq;
 
244
COMMENT ON TEXT SEARCH PARSER my_parser IS \*(AqSplits text into words\*(Aq;
 
245
COMMENT ON TEXT SEARCH TEMPLATE snowball IS \*(AqSnowball stemmer\*(Aq;
 
246
COMMENT ON TRIGGER my_trigger ON my_table IS \*(AqUsed for RI\*(Aq;
 
247
COMMENT ON TYPE complex IS \*(AqComplex number data type\*(Aq;
 
248
COMMENT ON VIEW my_view IS \*(AqView of departmental costs\*(Aq;
240
249
.fi
241
250
.if n \{\
242
251
.RE