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

1. COMMENT ON <object> IS {'sometext' | NULL}

3. <object> ::=
4. {DATABASE | SCHEMA}
5. | <basic-type> objectname
6. | USER username [USING PLUGIN pluginname]
7. | COLUMN relationname.fieldname
8. | [{PROCEDURE | FUNCTION}] PARAMETER
9. [packagename.]routinename.paramname
10. | {PROCEDURE | [EXTERNAL] FUNCTION}
11. [package_name.]routinename

13. <basic-type> ::=
14. CHARACTER SET | COLLATION | DOMAIN
15. | EXCEPTION     | FILTER    | GENERATOR
16. | INDEX         | PACKAGE   | ROLE
17. | SEQUENCE      | TABLE     | TRIGGER
18. | VIEW

Table 5.18.1.1 COMMENT ON Statement Parameters

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

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'; 5. Adding a comment for a package, its procedures and functions, and their parameters

``` 1. COMMENT ON PACKAGE APP_VAR IS 'Application Variables';

  1. COMMENT ON FUNCTION APP_VAR.GET_DATEBEGIN

  2. IS 'Returns the start date of the period';

  3. COMMENT ON PROCEDURE APP_VAR.SET_DATERANGE

  4. IS 'Set date range';

  5. COMMENT ON

  6. PROCEDURE PARAMETER APP_VAR.SET_DATERANGE.ADATEBEGIN
  7. IS 'Start Date'; ```