5.19. 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.19.1. COMMENT ON

Adds a comment to a metadata object

Available inDSQL

Syntax 

COMMENT ON <object> IS {'sometext' | NULL}
 
<object> ::=
    DATABASE
  | <schemaless-type> objectname
  | <schema-bound-type> [object-schema <period>] objectname
  | USER username [USING PLUGIN pluginname]
  | COLUMN [rel-schema <period>] relationname <period> fieldname
  | [{PROCEDURE | FUNCTION}] PARAMETER
      [<routine-location> <period>] routinename <period> paramname
  | {PROCEDURE | [EXTERNAL] FUNCTION}
      [<routine-location> <period>] routinename
  | [GLOBAL] MAPPING mappingname
 
<schema-less-type> ::= FILTER | ROLE | SCHEMA
 
<schema-bound-type> ::=
    CHARACTER SET | COLLATION | DOMAIN
  | EXCEPTION     | GENERATOR | INDEX
  | PACKAGE       | SEQUENCE  | TABLE
  | TRIGGER       | VIEW
 
<routine-location> ::=
    routine-schema
  | [ package-schema <period> ] package-name
  | package-name '%' PACKAGE
  | routine-schema '%' SCHEMA

Table 5.50. COMMENT ON Statement Parameters
ParameterDescription

sometext

Comment text

schemaless-type

A schemaless metadata object type

schema-bound-type

A schema-bound metadata object type

object-schema

Schema of the object. If not specified, the object will be located on the search path.

objectname

Metadata object name

username

Username

pluginname

User manager plugin name

rel-schema

Schema of the relation. If not specified, the relation will be located on the search path.

relationname

Name of table or view

fieldname

Name of the column

routinename

Name of stored procedure or function

paramname

Name of a stored procedure or function parameter

routine-schema

Schema containing the routine directly

package-schema

Schema containing the package

package_name

Name of the package containing the routine

mappingname

Name of a mapping

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. Comments on global mappings are stored in the security database.

🛑
Warning

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

5.19.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.19.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';