5.16. COMMENTS

Database objects and a database itself may contain comments. It is a convenient mechanism for documenting the development and maintenance of a database. Comments created with COMMENT ON will survive a gbak backup and restore.

5.16.1. COMMENT ON

Used for

Documenting metadata

Available in

DSQL

Syntax

  1. COMMENT ON <object> IS {'sometext' | NULL}
  3. <object> ::=
  4.     DATABASE
  5.   | <basic-type> objectname
  6.   | COLUMN relationname.fieldname
  7.   | PARAMETER procname.paramname
  9. <basic-type> ::=
  10.     CHARACTER SET
  11.   | COLLATION
  12.   | DOMAIN
  13.   | EXCEPTION
  14.   | EXTERNAL FUNCTION
  15.   | FILTER
  16.   | GENERATOR
  17.   | INDEX
  18.   | PROCEDURE
  19.   | ROLE
  20.   | SEQUENCE
  21.   | TABLE
  22.   | TRIGGER
  23.   | VIEW
Table 61. COMMENT ON Statement Parameters
ParameterDescription

sometext

Comment text

basic-type

Metadata object type

objectname

Metadata object name

relationname

Name of table or view

procname

Name of stored procedure

paramname

Name of a stored procedure parameter

The COMMENT ON statement adds comments for database objects (metadata). Comments are saved to text fields of the BLOB type in the RDB$DESCRIPTION column of the corresponding system tables. Client applications can view comments from these fields.

If you add an empty comment (“‘’”), it will be saved as NULL in the database.

The table or procedure owner and Administrators have the authority to use COMMENT ON.

Examples using COMMENT ON

  1. Adding a comment for the current database

    1. COMMENT ON DATABASE IS 'It is a test (''my.fdb'') database';

  2. Adding a comment for the METALS table

    1. COMMENT ON TABLE METALS IS 'Metal directory';

  3. Adding a comment for the ISALLOY field in the METALS table

    1. COMMENT ON COLUMN METALS.ISALLOY IS '0 = fine metal, 1 = alloy';

  4. Adding a comment for a parameter

    1. COMMENT ON PARAMETER ADD_EMP_PROJ.EMP_NO IS 'Employee ID';