~vcs-imports/mammoth-replicator/trunk

FUNCTION <replaceable class="PARAMETER">func_name</replaceable> (<replaceable class="PARAMETER">arg1_type</replaceable>, <replaceable class="PARAMETER">arg2_type</replaceable>, ...) |

INDEX <replaceable class="PARAMETER">object_name</replaceable> |

LARGE OBJECT <replaceable class="PARAMETER">large_object_oid</replaceable> |

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> |

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> |

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>

} IS <replaceable class="PARAMETER">'text'</replaceable>

</synopsis>

</refsynopsisdiv>

<title>Description</title>

<para>

<command>COMMENT</command> stores a comment about a database object.

</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>

Comments can be

easily retrieved with the <application>psql</application> commands

<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</>

(see <xref linkend="functions-info-comment-table">).

</para>

</refsect1>

<title>Parameters</title>

<term><replaceable class="parameter">object_name</replaceable></term>

<term><replaceable class="parameter">table_name.column_name</replaceable></term>

<term><replaceable class="parameter">constraint_name</replaceable></term>

<term><replaceable class="parameter">trigger_name</replaceable></term>

<para>

The name of the object to be commented. Names of tables,

aggregates, domains, functions, indexes, operators, operator classes,

sequences, types, and views may be schema-qualified.

</para>

</listitem>

</varlistentry>

100

<para>

101

The argument data type of the aggregate function, or

102

<literal>*</literal> if the function accepts any data type.

103

</para>

104

</listitem>

105

</varlistentry>

106

107

108

<term><replaceable class="parameter">large_object_oid</replaceable></term>

109

110

<para>

111

The OID of the large object.

112

</para>

113

</listitem>

114

</varlistentry>

115

116

117

<term><literal>PROCEDURAL</literal></term>

118

119

120

<para>

121

This is a noise word.

122

</para>

123

</listitem>

124

</varlistentry>

125

126

127

<term><replaceable>sourcetype</replaceable></term>

128

129

<para>

130

The name of the source data type of the cast.

131

</para>

132

</listitem>

133

</varlistentry>

134

135

136

<term><replaceable>targettype</replaceable></term>

137

138

<para>

139

The name of the target data type of the cast.

140

</para>

141

</listitem>

142

</varlistentry>

143

144

145

146

147

<para>

148

The new comment, written as a string literal; or <literal>NULL</>

149

to drop the comment.

150

</para>

151

</listitem>

152

</varlistentry>

153

154

</variablelist>

155

</refsect1>

156

157

158

<title>Notes</title>

159

160

<para>

161

A comment for a database can only be created in that database,

162

and will only be visible in that database, not in other databases.

163

</para>

164

165

<para>

166

There is presently no security mechanism for comments: any user

167

connected to a database can see all the comments for objects in

168

that database (although only superusers can change comments for

169

objects that they don't own). Therefore, don't put

170

security-critical information in comments.

171

</para>

172

</refsect1>

173

174

175

<title>Examples</title>

176

177

<para>

178

Attach a comment to the table <literal>mytable</literal>:

179

180

181

COMMENT ON TABLE mytable IS 'This is my table.';

182

</programlisting>

183

184

Remove it again:

185

186

187

COMMENT ON TABLE mytable IS NULL;

188

</programlisting>

189

</para>

190

191

<para>

192

Some more examples:

193

194

195

COMMENT ON AGGREGATE my_aggregate (double precision) IS 'Computes sample variance';

196

COMMENT ON CAST (text AS int4) IS 'Allow casts from text to int4';

197

COMMENT ON COLUMN my_table.my_column IS 'Employee ID number';

198

COMMENT ON CONVERSION my_conv IS 'Conversion to Unicode';

199

COMMENT ON DATABASE my_database IS 'Development Database';

200

COMMENT ON DOMAIN my_domain IS 'Email Address Domain';

201

COMMENT ON FUNCTION my_function (timestamp) IS 'Returns Roman Numeral';

202

COMMENT ON INDEX my_index IS 'Enforces uniqueness on employee ID';

203

COMMENT ON LANGUAGE plpython IS 'Python support for stored procedures';

204

COMMENT ON LARGE OBJECT 346344 IS 'Planning document';

205

COMMENT ON OPERATOR ^ (text, text) IS 'Performs intersection of two texts';

206

COMMENT ON OPERATOR ^ (NONE, text) IS 'This is a prefix operator on text';

207

COMMENT ON OPERATOR CLASS int4ops USING btree IS '4 byte integer operators for btrees';

208

COMMENT ON RULE my_rule ON my_table IS 'Logs updates of employee records';

209

COMMENT ON SCHEMA my_schema IS 'Departmental data';

210

COMMENT ON SEQUENCE my_sequence IS 'Used to generate primary keys';

211

COMMENT ON TABLE my_schema.my_table IS 'Employee Information';

212

COMMENT ON TRIGGER my_trigger ON my_table IS 'Used for RI';

213

COMMENT ON TYPE complex IS 'Complex number data type';

214

COMMENT ON VIEW my_view IS 'View of departmental costs';

215

</programlisting>

216

</para>

217

</refsect1>

218

219

220

<title>Compatibility</title>

221

222

<para>

223

There is no <command>COMMENT</command> command in the SQL standard.

224

</para>

225

</refsect1>

226

</refentry>

227

228

<!-- Keep this comment at the end of the file

229

Local variables:

230

mode: sgml

231

sgml-omittag:t

232

sgml-shorttag:t

233

sgml-minimize-attributes:nil

234

sgml-always-quote-attributes:t

235

sgml-indent-step:1

236

sgml-indent-data:t

237

sgml-parent-document:nil

238

sgml-default-dtd-file:"../reference.ced"

239

sgml-exposed-tags:nil

240

sgml-local-catalogs:"/usr/lib/sgml/catalog"

241

sgml-local-ecat-files:nil

242

End:

243

-->

Older »