5.18. Comments

Database objects and a database itself may be annotated with 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.18.1. COMMENT ON

Used forDocumenting metadata

Available inDSQL

Syntax 

   |COMMENT ON <object> IS {'sometext' | NULL}
   | 
   |<object> ::=
   |    {DATABASE | SCHEMA}
   |  | <basic-type> objectname
   |  | USER username [USING PLUGIN pluginname]
   |  | COLUMN relationname.fieldname
   |  | [{PROCEDURE | FUNCTION}] PARAMETER
   |      [packagename.]routinename.paramname
   |  | {PROCEDURE | [EXTERNAL] FUNCTION}
   |      [package_name.]routinename
   | 
   |<basic-type> ::=
   |    CHARACTER SET | COLLATION | DOMAIN
   |  | EXCEPTION     | FILTER    | GENERATOR
   |  | INDEX         | PACKAGE   | ROLE
   |  | SEQUENCE      | TABLE     | TRIGGER
   |  | VIEW

Table 5.48. COMMENT ON Statement Parameters
ParameterDescription

sometext

Comment text

basic-type

Metadata object type

objectname

Metadata object name

username

Username

pluginname

User manager plugin name

relationname

Name of table or view

fieldname

Name of the column

package_name

Name of the package

routinename

Name of stored procedure or function

paramname

Name of a stored procedure or function parameter

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

ⓘ
Note

  1. If you add an empty comment (''), it will be saved as NULL in the database.

  2. By default, the COMMENT ON USER statement will create comments on users managed by the default user manager (the first plugin listed in the UserManager config option). The USING PLUGIN can be used to comment on a user managed by a different user manager.

  3. Comments on users are not stored for the Legacy_UserManager.

  4. Comments on users are stored in the security database.

  5. SCHEMA is currently a synonym for DATABASE; this may change in a future version, so we recommend to always use DATABASE

🛑
Warning

Comments on users are visible to that user through the SEC$USERS virtual table.

5.18.1.1. Who Can Add a Comment

The COMMENT ON statement can be executed by:

  • Administrators

  • The owner of the object that is commented on

  • Users with the ALTER ANY object_type privilege, where object_type is the type of object commented on (e.g. PROCEDURE)

5.18.1.2. Examples using COMMENT ON

  1. Adding a comment for the current database

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

  2. Adding a comment for the METALS table

      |COMMENT ON TABLE METALS IS 'Metal directory';

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

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

  4. Adding a comment for a parameter

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

  5. Adding a comment for a package, its procedures and functions, and their parameters

       |COMMENT ON PACKAGE APP_VAR IS 'Application Variables';
   | 
   |COMMENT ON FUNCTION APP_VAR.GET_DATEBEGIN
   |IS 'Returns the start date of the period';
   | 
   |COMMENT ON PROCEDURE APP_VAR.SET_DATERANGE
   |IS 'Set date range';
   | 
   |COMMENT ON
   |PROCEDURE PARAMETER APP_VAR.SET_DATERANGE.ADATEBEGIN
   |IS 'Start Date';