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.18.1.1 COMMENT ON Statement Parameters

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