rules repository

G-1260

🆓
Info

Try to define a comment for each table.

Modeling

Rule Details

Severity Level
Info
Quality Area
Maintainability
Fixing times
60 mins
Other
Database Support
OracleDB (v12.2.0 +)

Reason

Providing a descriptive comment for every table makes the schema more self-explanatory. This additional layer of documentation helps new team members understand the table’s purpose and context without needing external references or detailed conversations. It also guides future maintainers when they need to make changes or troubleshoot issues.

Example

Non-Compliant Example

create table parent (
   parent_id   raw(16) default sys_guid() not null,
   parent_name varchar2(100 char)         not null,
   constraint parent_pk primary key (parent_id),
   constraint parent_uk1 unique (parent_name)
);

Compliant Solution - ★★★★★

create table parent (
   parent_id   raw(16) default sys_guid() not null,
   parent_name varchar2(100 char)         not null,
   constraint parent_pk primary key (parent_id),
   constraint parent_uk1 unique (parent_name)
);

comment on table parent is 'Some useful description of a parent row.';

Tests

Test SQL query

select owner || '.' || table_name as identifier,
       'Missing comment on ' || lower(table_type) || ' ' || table_name as message
  from dba_tab_comments c
 where table_type in (#ObjectTypesWithPrimaryKey#)
   and owner in (#SchemaNames#)
   and table_name not like 'BIN$%' -- not a table in recycle bin
   and comments is null
   and table_name not like 'AQ$%'
   and not exists (
          select 1
           from dba_tables t
           where t.iot_type is not null
              and t.owner = c.owner
              and t.table_name = c.table_name
       )
 order by owner, table_name

Test results

IdentifierMessageMigration
DBL_OWNER.PARENTMissing comment on table PARENT-

Parameters

Use parameters to customize the rule to your needs.

ParameterDescriptionDefault Value
ObjectTypesWithPrimaryKeyComma separated list of object types that should be defined with a primary key.table
SchemaNamesComma separated list of database schemas owning the database objects of an application.dbl_owner

References

← Previous
G-1250
Try to define a business key for each table.
Next →
G-1270
Try to define a comment for each column.