MDEV-25325 built-in documentation for performance_schema tables

Improve documentation of performance_schema tables by appending COLUMN
comments to tables. Additionally improve test coverage and update corresponding
tests.

This is part of the patch covering newer columns and tables in 10.5.

7 files changed, 78 insertions, 78 deletions

diff --git a/storage/perfschema/table_md_locks.cc b/storage/perfschema/table_md_locks.cc
index 9f78750e89b..a6bfdd25b68 100644
--- a/storage/perfschema/table_md_locks.cc
+++ b/storage/perfschema/table_md_locks.cc
@@ -49,16 +49,16 @@ table_metadata_locks::m_share=
   sizeof(PFS_simple_index),
   &m_table_lock,
   { C_STRING_WITH_LEN("CREATE TABLE metadata_locks("
-  "OBJECT_TYPE VARCHAR(64) not null,"
-  "OBJECT_SCHEMA VARCHAR(64),"
-  "OBJECT_NAME VARCHAR(64),"
-  "OBJECT_INSTANCE_BEGIN BIGINT unsigned not null,"
-  "LOCK_TYPE VARCHAR(32) not null,"
-  "LOCK_DURATION VARCHAR(32) not null,"
-  "LOCK_STATUS VARCHAR(32) not null,"
-  "SOURCE VARCHAR(64),"
-  "OWNER_THREAD_ID BIGINT unsigned,"
-  "OWNER_EVENT_ID BIGINT unsigned)")},
+  "OBJECT_TYPE VARCHAR(64) not null comment 'Object type. One of BACKUP, COMMIT, EVENT, FUNCTION, GLOBAL, LOCKING SERVICE, PROCEDURE, SCHEMA, TABLE, TABLESPACE, TRIGGER (unused) or USER LEVEL LOCK.',"
+  "OBJECT_SCHEMA VARCHAR(64) comment 'Object schema.',"
+  "OBJECT_NAME VARCHAR(64) comment 'Object name.',"
+  "OBJECT_INSTANCE_BEGIN BIGINT unsigned not null comment 'Address in memory of the instrumented object.',"
+  "LOCK_TYPE VARCHAR(32) not null comment 'Lock type. One of BACKUP_FTWRL1, BACKUP_START, BACKUP_TRANS_DML, EXCLUSIVE, INTENTION_EXCLUSIVE, SHARED, SHARED_HIGH_PRIO, SHARED_NO_READ_WRITE, SHARED_NO_WRITE, SHARED_READ, SHARED_UPGRADABLE or SHARED_WRITE.',"
+  "LOCK_DURATION VARCHAR(32) not null comment 'Lock duration. One of EXPLICIT (locks released by explicit action, for example a global lock acquired with FLUSH TABLES WITH READ LOCK) , STATEMENT (locks implicitly released at statement end) or TRANSACTION (locks implicitly released at transaction end).',"
+  "LOCK_STATUS VARCHAR(32) not null comment 'Lock status. One of GRANTED, KILLED, PENDING, POST_RELEASE_NOTIFY, PRE_ACQUIRE_NOTIFY, TIMEOUT or VICTIM.',"
+  "SOURCE VARCHAR(64) comment 'Source file containing the instrumented code that produced the event, as well as the line number where the instrumentation occurred. This allows one to examine the source code involved.',"
+  "OWNER_THREAD_ID BIGINT unsigned comment 'Thread that requested the lock.',"
+  "OWNER_EVENT_ID BIGINT unsigned comment 'Event that requested the lock.')")},
   false  /* perpetual */
 };
 
diff --git a/storage/perfschema/table_mems_by_account_by_event_name.cc b/storage/perfschema/table_mems_by_account_by_event_name.cc
index 5c83c225d11..7a0254d91a2 100644
--- a/storage/perfschema/table_mems_by_account_by_event_name.cc
+++ b/storage/perfschema/table_mems_by_account_by_event_name.cc
@@ -51,19 +51,19 @@ table_mems_by_account_by_event_name::m_share=
   sizeof(pos_mems_by_account_by_event_name),
   &m_table_lock,
   { C_STRING_WITH_LEN("CREATE TABLE memory_summary_by_account_by_event_name("
-  "USER CHAR(32) collate utf8_bin default null,"
-  "HOST CHAR(60) collate utf8_bin default null,"
-  "EVENT_NAME VARCHAR(128) not null,"
-  "COUNT_ALLOC BIGINT unsigned not null,"
-  "COUNT_FREE BIGINT unsigned not null,"
-  "SUM_NUMBER_OF_BYTES_ALLOC BIGINT unsigned not null,"
-  "SUM_NUMBER_OF_BYTES_FREE BIGINT unsigned not null,"
-  "LOW_COUNT_USED BIGINT not null,"
-  "CURRENT_COUNT_USED BIGINT not null,"
-  "HIGH_COUNT_USED BIGINT not null,"
-  "LOW_NUMBER_OF_BYTES_USED BIGINT not null,"
-  "CURRENT_NUMBER_OF_BYTES_USED BIGINT not null,"
-  "HIGH_NUMBER_OF_BYTES_USED BIGINT not null)")},
+  "USER CHAR(32) collate utf8_bin default null comment 'User portion of the account.',"
+  "HOST CHAR(60) collate utf8_bin default null comment 'Host portion of the account.',"
+  "EVENT_NAME VARCHAR(128) not null comment 'Event name.',"
+  "COUNT_ALLOC BIGINT unsigned not null comment 'Total number of allocations to memory.',"
+  "COUNT_FREE BIGINT unsigned not null comment 'Total number of attempts to free the allocated memory.',"
+  "SUM_NUMBER_OF_BYTES_ALLOC BIGINT unsigned not null comment 'Total number of bytes allocated.',"
+  "SUM_NUMBER_OF_BYTES_FREE BIGINT unsigned not null comment 'Total number of bytes freed',"
+  "LOW_COUNT_USED BIGINT not null comment 'Lowest number of allocated blocks (lowest value of CURRENT_COUNT_USED).',"
+  "CURRENT_COUNT_USED BIGINT not null comment 'Currently allocated blocks that have not been freed (COUNT_ALLOC minus COUNT_FREE).',"
+  "HIGH_COUNT_USED BIGINT not null comment 'Highest number of allocated blocks (highest value of CURRENT_COUNT_USED).',"
+  "LOW_NUMBER_OF_BYTES_USED BIGINT not null comment 'Lowest number of bytes used.',"
+  "CURRENT_NUMBER_OF_BYTES_USED BIGINT not null comment 'Current number of bytes used (total allocated minus total freed).',"
+  "HIGH_NUMBER_OF_BYTES_USED BIGINT not null comment 'Highest number of bytes used.')")},
   false  /* perpetual */
 };
 
diff --git a/storage/perfschema/table_mems_by_host_by_event_name.cc b/storage/perfschema/table_mems_by_host_by_event_name.cc
index 0921dfa49c8..4b91d0420d5 100644
--- a/storage/perfschema/table_mems_by_host_by_event_name.cc
+++ b/storage/perfschema/table_mems_by_host_by_event_name.cc
@@ -51,18 +51,18 @@ table_mems_by_host_by_event_name::m_share=
   sizeof(PFS_simple_index),
   &m_table_lock,
   { C_STRING_WITH_LEN("CREATE TABLE memory_summary_by_host_by_event_name("
-  "HOST CHAR(60) collate utf8_bin default null,"
-  "EVENT_NAME VARCHAR(128) not null,"
-  "COUNT_ALLOC BIGINT unsigned not null,"
-  "COUNT_FREE BIGINT unsigned not null,"
-  "SUM_NUMBER_OF_BYTES_ALLOC BIGINT unsigned not null,"
-  "SUM_NUMBER_OF_BYTES_FREE BIGINT unsigned not null,"
-  "LOW_COUNT_USED BIGINT not null,"
-  "CURRENT_COUNT_USED BIGINT not null,"
-  "HIGH_COUNT_USED BIGINT not null,"
-  "LOW_NUMBER_OF_BYTES_USED BIGINT not null,"
-  "CURRENT_NUMBER_OF_BYTES_USED BIGINT not null,"
-  "HIGH_NUMBER_OF_BYTES_USED BIGINT not null)")},
+  "HOST CHAR(60) collate utf8_bin default null comment 'Host portion of the account.',"
+  "EVENT_NAME VARCHAR(128) not null comment 'Event name.',"
+  "COUNT_ALLOC BIGINT unsigned not null comment 'Total number of allocations to memory.',"
+  "COUNT_FREE BIGINT unsigned not null comment 'Total number of attempts to free the allocated memory.',"
+  "SUM_NUMBER_OF_BYTES_ALLOC BIGINT unsigned not null comment 'Total number of bytes allocated.',"
+  "SUM_NUMBER_OF_BYTES_FREE BIGINT unsigned not null comment 'Total number of bytes freed',"
+  "LOW_COUNT_USED BIGINT not null comment 'Lowest number of allocated blocks (lowest value of CURRENT_COUNT_USED).',"
+  "CURRENT_COUNT_USED BIGINT not null comment 'Currently allocated blocks that have not been freed (COUNT_ALLOC minus COUNT_FREE).',"
+  "HIGH_COUNT_USED BIGINT not null comment 'Highest number of allocated blocks (highest value of CURRENT_COUNT_USED).',"
+  "LOW_NUMBER_OF_BYTES_USED BIGINT not null comment 'Lowest number of bytes used.',"
+  "CURRENT_NUMBER_OF_BYTES_USED BIGINT not null comment 'Current number of bytes used (total allocated minus total freed).',"
+  "HIGH_NUMBER_OF_BYTES_USED BIGINT not null comment 'Highest number of bytes used.')")},
   false  /* perpetual */
 };
 
diff --git a/storage/perfschema/table_mems_by_thread_by_event_name.cc b/storage/perfschema/table_mems_by_thread_by_event_name.cc
index 9e36cb76dd7..3c25e948cbf 100644
--- a/storage/perfschema/table_mems_by_thread_by_event_name.cc
+++ b/storage/perfschema/table_mems_by_thread_by_event_name.cc
@@ -51,18 +51,18 @@ table_mems_by_thread_by_event_name::m_share=
   sizeof(PFS_simple_index),
   &m_table_lock,
   { C_STRING_WITH_LEN("CREATE TABLE memory_summary_by_thread_by_event_name("
-  "THREAD_ID BIGINT unsigned not null,"
-  "EVENT_NAME VARCHAR(128) not null,"
-  "COUNT_ALLOC BIGINT unsigned not null,"
-  "COUNT_FREE BIGINT unsigned not null,"
-  "SUM_NUMBER_OF_BYTES_ALLOC BIGINT unsigned not null,"
-  "SUM_NUMBER_OF_BYTES_FREE BIGINT unsigned not null,"
-  "LOW_COUNT_USED BIGINT not null,"
-  "CURRENT_COUNT_USED BIGINT not null,"
-  "HIGH_COUNT_USED BIGINT not null,"
-  "LOW_NUMBER_OF_BYTES_USED BIGINT not null,"
-  "CURRENT_NUMBER_OF_BYTES_USED BIGINT not null,"
-  "HIGH_NUMBER_OF_BYTES_USED BIGINT not null)")},
+  "THREAD_ID BIGINT unsigned not null comment 'Thread id.',"
+  "EVENT_NAME VARCHAR(128) not null comment 'Event name.',"
+  "COUNT_ALLOC BIGINT unsigned not null comment 'Total number of allocations to memory.',"
+  "COUNT_FREE BIGINT unsigned not null comment 'Total number of attempts to free the allocated memory.',"
+  "SUM_NUMBER_OF_BYTES_ALLOC BIGINT unsigned not null comment 'Total number of bytes allocated.',"
+  "SUM_NUMBER_OF_BYTES_FREE BIGINT unsigned not null comment 'Total number of bytes freed',"
+  "LOW_COUNT_USED BIGINT not null comment 'Lowest number of allocated blocks (lowest value of CURRENT_COUNT_USED).',"
+  "CURRENT_COUNT_USED BIGINT not null comment 'Currently allocated blocks that have not been freed (COUNT_ALLOC minus COUNT_FREE).',"
+  "HIGH_COUNT_USED BIGINT not null comment 'Highest number of allocated blocks (highest value of CURRENT_COUNT_USED).',"
+  "LOW_NUMBER_OF_BYTES_USED BIGINT not null comment 'Lowest number of bytes used.',"
+  "CURRENT_NUMBER_OF_BYTES_USED BIGINT not null comment 'Current number of bytes used (total allocated minus total freed).',"
+  "HIGH_NUMBER_OF_BYTES_USED BIGINT not null comment 'Highest number of bytes used.')")},
   false  /* perpetual */
 };
 
diff --git a/storage/perfschema/table_mems_by_user_by_event_name.cc b/storage/perfschema/table_mems_by_user_by_event_name.cc
index 5d5ee89d6bd..dbb4b19c430 100644
--- a/storage/perfschema/table_mems_by_user_by_event_name.cc
+++ b/storage/perfschema/table_mems_by_user_by_event_name.cc
@@ -51,18 +51,18 @@ table_mems_by_user_by_event_name::m_share=
   sizeof(PFS_simple_index),
   &m_table_lock,
   { C_STRING_WITH_LEN("CREATE TABLE memory_summary_by_user_by_event_name("
-  "USER CHAR(32) collate utf8_bin default null,"
-  "EVENT_NAME VARCHAR(128) not null,"
-  "COUNT_ALLOC BIGINT unsigned not null,"
-  "COUNT_FREE BIGINT unsigned not null,"
-  "SUM_NUMBER_OF_BYTES_ALLOC BIGINT unsigned not null,"
-  "SUM_NUMBER_OF_BYTES_FREE BIGINT unsigned not null,"
-  "LOW_COUNT_USED BIGINT not null,"
-  "CURRENT_COUNT_USED BIGINT not null,"
-  "HIGH_COUNT_USED BIGINT not null,"
-  "LOW_NUMBER_OF_BYTES_USED BIGINT not null,"
-  "CURRENT_NUMBER_OF_BYTES_USED BIGINT not null,"
-  "HIGH_NUMBER_OF_BYTES_USED BIGINT not null)")},
+  "USER CHAR(32) collate utf8_bin default null comment 'User portion of the account.',"
+  "EVENT_NAME VARCHAR(128) not null comment 'Event name.',"
+  "COUNT_ALLOC BIGINT unsigned not null comment 'Total number of allocations to memory.',"
+  "COUNT_FREE BIGINT unsigned not null comment 'Total number of attempts to free the allocated memory.',"
+  "SUM_NUMBER_OF_BYTES_ALLOC BIGINT unsigned not null comment 'Total number of bytes allocated.',"
+  "SUM_NUMBER_OF_BYTES_FREE BIGINT unsigned not null comment 'Total number of bytes freed',"
+  "LOW_COUNT_USED BIGINT not null comment 'Lowest number of allocated blocks (lowest value of CURRENT_COUNT_USED).',"
+  "CURRENT_COUNT_USED BIGINT not null comment 'Currently allocated blocks that have not been freed (COUNT_ALLOC minus COUNT_FREE).',"
+  "HIGH_COUNT_USED BIGINT not null comment 'Highest number of allocated blocks (highest value of CURRENT_COUNT_USED).',"
+  "LOW_NUMBER_OF_BYTES_USED BIGINT not null comment 'Lowest number of bytes used.',"
+  "CURRENT_NUMBER_OF_BYTES_USED BIGINT not null comment 'Current number of bytes used (total allocated minus total freed).',"
+  "HIGH_NUMBER_OF_BYTES_USED BIGINT not null comment 'Highest number of bytes used.')")},
   false  /* perpetual */
 };
 
diff --git a/storage/perfschema/table_mems_global_by_event_name.cc b/storage/perfschema/table_mems_global_by_event_name.cc
index 93496e38cf4..4a6f7e86fed 100644
--- a/storage/perfschema/table_mems_global_by_event_name.cc
+++ b/storage/perfschema/table_mems_global_by_event_name.cc
@@ -51,17 +51,17 @@ table_mems_global_by_event_name::m_share=
   sizeof(pos_t),
   &m_table_lock,
   { C_STRING_WITH_LEN("CREATE TABLE memory_summary_global_by_event_name("
-  "EVENT_NAME VARCHAR(128) not null,"
-  "COUNT_ALLOC BIGINT unsigned not null,"
-  "COUNT_FREE BIGINT unsigned not null,"
-  "SUM_NUMBER_OF_BYTES_ALLOC BIGINT unsigned not null,"
-  "SUM_NUMBER_OF_BYTES_FREE BIGINT unsigned not null,"
-  "LOW_COUNT_USED BIGINT not null,"
-  "CURRENT_COUNT_USED BIGINT not null,"
-  "HIGH_COUNT_USED BIGINT not null,"
-  "LOW_NUMBER_OF_BYTES_USED BIGINT not null,"
-  "CURRENT_NUMBER_OF_BYTES_USED BIGINT not null,"
-  "HIGH_NUMBER_OF_BYTES_USED BIGINT not null)")},
+  "EVENT_NAME VARCHAR(128) not null comment 'Event name.',"
+  "COUNT_ALLOC BIGINT unsigned not null comment 'Total number of allocations to memory.',"
+  "COUNT_FREE BIGINT unsigned not null comment 'Total number of attempts to free the allocated memory.',"
+  "SUM_NUMBER_OF_BYTES_ALLOC BIGINT unsigned not null comment 'Total number of bytes allocated.',"
+  "SUM_NUMBER_OF_BYTES_FREE BIGINT unsigned not null comment 'Total number of bytes freed',"
+  "LOW_COUNT_USED BIGINT not null comment 'Lowest number of allocated blocks (lowest value of CURRENT_COUNT_USED).',"
+  "CURRENT_COUNT_USED BIGINT not null comment 'Currently allocated blocks that have not been freed (COUNT_ALLOC minus COUNT_FREE).',"
+  "HIGH_COUNT_USED BIGINT not null comment 'Highest number of allocated blocks (highest value of CURRENT_COUNT_USED).',"
+  "LOW_NUMBER_OF_BYTES_USED BIGINT not null comment 'Lowest number of bytes used.',"
+  "CURRENT_NUMBER_OF_BYTES_USED BIGINT not null comment 'Current number of bytes used (total allocated minus total freed).',"
+  "HIGH_NUMBER_OF_BYTES_USED BIGINT not null comment 'Highest number of bytes used.')")},
   false  /* perpetual */
 };
 
diff --git a/storage/perfschema/table_replication_applier_status_by_worker.cc b/storage/perfschema/table_replication_applier_status_by_worker.cc
index 4c7ca612e0b..8b81e7eed6d 100644
--- a/storage/perfschema/table_replication_applier_status_by_worker.cc
+++ b/storage/perfschema/table_replication_applier_status_by_worker.cc
@@ -54,14 +54,14 @@ table_replication_applier_status_by_worker::m_share=
   sizeof(pos_t), /* ref length */
   &m_table_lock,
   { C_STRING_WITH_LEN("CREATE TABLE replication_applier_status_by_worker("
-  "CHANNEL_NAME CHAR(64) collate utf8_general_ci not null,"
-  "WORKER_ID BIGINT UNSIGNED not null,"
-  "THREAD_ID BIGINT UNSIGNED,"
-  "SERVICE_STATE ENUM('ON','OFF') not null,"
-  "LAST_SEEN_TRANSACTION CHAR(57) not null,"
-  "LAST_ERROR_NUMBER INTEGER not null,"
-  "LAST_ERROR_MESSAGE VARCHAR(1024) not null,"
-  "LAST_ERROR_TIMESTAMP TIMESTAMP(0) not null)") },
+  "CHANNEL_NAME CHAR(64) collate utf8_general_ci not null comment 'Name of replication channel through which the transaction is received.',"
+  "WORKER_ID BIGINT UNSIGNED not null comment 'Worker identifier.,"
+  "THREAD_ID BIGINT UNSIGNED comment 'Thread_Id as displayed in the performance_schema.threads table for thread with name ''thread/sql/rpl_parallel_thread''. THREAD_ID will be NULL when worker threads are stopped due to error/force stop.',"
+  "SERVICE_STATE ENUM('ON','OFF') not null comment 'Whether or not the thread is running.',"
+  "LAST_SEEN_TRANSACTION CHAR(57) not null comment 'Last GTID executed by worker',"
+  "LAST_ERROR_NUMBER INTEGER not null comment 'Last Error that occurred on a particular worker.',"
+  "LAST_ERROR_MESSAGE VARCHAR(1024) not null comment 'Last error specific message.',"
+  "LAST_ERROR_TIMESTAMP TIMESTAMP(0) not null comment 'Time stamp of last error.')") },
   false  /* perpetual */
 };