15.6.7.7 MySQL 诊断区域
SQL 语句生成诊断信息,填充诊断区域。标准 SQL 有一个诊断区域栈,包含每个嵌套执行上下文的诊断区域。标准 SQL 还支持GET STACKED DIAGNOSTICS
语法,用于在条件处理器执行时引用第二个诊断区域。
以下讨论描述了 MySQL 诊断区域的结构、MySQL 认识的信息项、语句如何清除和设置诊断区域,以及诊断区域如何被推到和弹出栈。
诊断区域包含两种信息:
-
语句信息,例如发生的条件数或影响行数。
-
诊断信息,例如错误代码和消息。如果语句引发多个条件,这部分诊断信息中每个条件都有一个诊断区块。如果语句不引发任何条件,这部分诊断信息为空。
对于产生三个条件的语句,诊断信息部分包含以下信息:
Statement information:
row count
... other statement information items ...
Condition area list:
Condition area 1:
error code for condition 1
error message for condition 1
... other condition information items ...
Condition area 2:
error code for condition 2:
error message for condition 2
... other condition information items ...
Condition area 3:
error code for condition 3
error message for condition 3
... other condition information items ...
诊断信息部分包含语句和条件信息项。数字项是整数。字符项的字符集为 UTF-8。没有项可以是NULL
。如果语句或条件项不是由填充诊断信息的语句设置,它们的值是 0 或空字符串,取决于项数据类型。
诊断信息部分中的语句信息包含这些项:
-
NUMBER
: 表示有条件区块数量的整数。 -
ROW_COUNT
: 表示语句影响的行数。ROW_COUNT
的值与ROW_COUNT()
函数相同(见第14.15节,“信息函数”)。
诊断信息部分中的条件信息包含每个条件的区块。条件区块从 1 到NUMBER
语句条件项的值编号。如果NUMBER
是 0,不存在条件区块。
每个条件区域包含以下列表中的项目。所有项目都是标准SQL,except MYSQL_ERRNO
,这是MySQL扩展。定义适用于除信号生成的条件(即由SIGNAL
或RESIGNAL
语句生成的条件)。对于非信号条件,MySQL只填充未描述为空的条件项目。信号对条件区域的影响将在后面描述。
-
CLASS_ORIGIN
:RETURNED_SQLSTATE
值的类别字符串。如果RETURNED_SQLSTATE
值以SQL标准文档ISO 9075-2 (第24.1节,SQLSTATE)定义的类别值开头,CLASS_ORIGIN
是'ISO 9075'
。否则,CLASS_ORIGIN
是'MySQL'
。 -
SUBCLASS_ORIGIN
:RETURNED_SQLSTATE
值的子类别字符串。如果CLASS_ORIGIN
是'ISO 9075'
或RETURNED_SQLSTATE
以'000'
结尾,SUBCLASS_ORIGIN
是'ISO 9075'
。否则,SUBCLASS_ORIGIN
是'MySQL'
。 -
RETURNED_SQLSTATE
:条件的SQLSTATE
值字符串。 -
MESSAGE_TEXT
:条件的错误信息字符串。 -
MYSQL_ERRNO
: 一个整数,表示 MySQL 错误代码的条件。 -
CONSTRAINT_CATALOG
,CONSTRAINT_SCHEMA
,CONSTRAINT_NAME
: 字符串,指示违反约束的目录、模式和名称。它们总是为空。 -
CATALOG_NAME
,SCHEMA_NAME
,TABLE_NAME
,COLUMN_NAME
: 字符串,指示与条件相关的目录、模式、表和列。它们总是为空。 -
CURSOR_NAME
: 一个字符串,指示游标名称。这总是为空。
对于特定的错误,见服务器错误参考中的 RETURNED_SQLSTATE
, MESSAGE_TEXT
和 MYSQL_ERRNO
值。
如果一个SIGNAL
(或RESIGNAL
) 语句填充诊断区,它的SET
子句可以将任何条件信息项除RETURNED_SQLSTATE
外,分配给该项的合法值。SIGNAL
也设置了RETURNED_SQLSTATE
值,但不是直接在其SET
子句中。该值来自SIGNAL
语句的SQLSTATE
参数。
SIGNAL
也设置语句信息项。它将NUMBER
设置为1。它将ROW_COUNT
设置为错误时-1,否则为0。
非诊断性SQL语句自动填充诊断区,且可以使用SIGNAL
和RESIGNAL
语句来设置诊断区的内容。诊断区可以使用GET DIAGNOSTICS
提取特定项目,或者使用SHOW WARNINGS
或SHOW ERRORS
查看条件或错误。
SQL语句清除和设置诊断区如下:
-
服务器开始执行语句后,它将清除非诊断性语句的诊断区。诊断语句不清除诊断区。这些语句是诊断语句:
-
如果语句引发条件,诊断区将清除早期语句的条件,唯一的例外是由
GET DIAGNOSTICS
和RESIGNAL
引发的条件,它们将被添加到诊断区而不清除它。
因此,即使语句在执行时不正常清除诊断区,但如果语句引发条件,它也会清除诊断区。
以下示例展示了各种语句对诊断区的影响,使用SHOW WARNINGS
来显示存储在诊断区中的信息。
这个DROP TABLE
语句清除诊断区并在条件发生时填充它:
mysql> DROP TABLE IF EXISTS test.no_such_table;
Query OK, 0 rows affected, 1 warning (0.01 sec)
mysql> SHOW WARNINGS;
+-------+------+------------------------------------+
| Level | Code | Message |
+-------+------+------------------------------------+
| Note | 1051 | Unknown table 'test.no_such_table' |
+-------+------+------------------------------------+
1 row in set (0.00 sec)
这个SET
语句生成错误,所以它清除并填充诊断区:
mysql> SET @x = @@x;
ERROR 1193 (HY000): Unknown system variable 'x'
mysql> SHOW WARNINGS;
+-------+------+-----------------------------+
| Level | Code | Message |
+-------+------+-----------------------------+
| Error | 1193 | Unknown system variable 'x' |
+-------+------+-----------------------------+
1 row in set (0.00 sec)
前一个SET
语句产生了单个条件,所以在这个点上,GET DIAGNOSTICS
的唯一有效条件号是1。下一个语句使用条件号2,这个警告将被添加到诊断区而不清除它:
mysql> GET DIAGNOSTICS CONDITION 2 @p = MESSAGE_TEXT;
Query OK, 0 rows affected, 1 warning (0.00 sec)
mysql> SHOW WARNINGS;
+-------+------+------------------------------+
| Level | Code | Message |
+-------+------+------------------------------+
| Error | 1193 | Unknown system variable 'xx' |
| Error | 1753 | Invalid condition number |
+-------+------+------------------------------+
2 rows in set (0.00 sec)
现在诊断信息区中有两个条件,所以同一个GET DIAGNOSTICS
语句都可以成功:
mysql> GET DIAGNOSTICS CONDITION 2 @p = MESSAGE_TEXT;
Query OK, 0 rows affected (0.00 sec)
mysql> SELECT @p;
+--------------------------+
| @p |
+--------------------------+
| Invalid condition number |
+--------------------------+
1 row in set (0.01 sec)
当诊断信息区栈推送到时,当前诊断信息区变为栈中诊断信息区,并创建一个它的副本作为新的当前诊断信息区。诊断信息区在以下情况下被推送和弹出:
-
存储程序执行
推送发生在程序执行前,弹出发生在后面。如果存储程序结束时,处理器正在执行,那么可能会有多个诊断信息区弹出;这是在没有合适的处理器或是
RETURN
处理器中引起的。弹出诊断信息区中的警告或错误条件都被添加到当前诊断信息区中,除了触发器外,只有错误被添加。存储程序结束时,调用者在其当前诊断信息区中可以看到这些条件。
-
存储程序中的条件处理器执行
当条件处理器激活导致推送时,堆栈诊断区是存储程序中当前的诊断区。新的当前诊断区是处理器的当前诊断区。
GET [CURRENT] DIAGNOSTICS
和GET STACKED DIAGNOSTICS
可以在处理器中访问当前(处理器)和堆栈(存储程序)的诊断区内容。初始情况下,他们返回相同的结果,但在处理器中执行语句修改了当前诊断区,根据正常规则清除和设置其内容(见诊断区的清除和填充方式)。堆栈诊断区除了RESIGNAL
语句外,不能被处理器中执行的语句修改。如果处理器执行成功,当前(处理器)诊断区将弹出,堆栈(存储程序)诊断区再次变成当前诊断区。处理器诊断区添加的条件也被添加到当前诊断区中。
-
在存储程序中,
RESIGNAL
语句将可执行时的错误信息传递给外层语句。RESIGNAL
可能在传递前修改一些或所有信息,详见第15.6.7.4节,“RESIGNAL 语句”。
某些系统变量控制或与诊断区的某些方面相关:
-
max_error_count
控制诊断区中的条件数量。如果出现的条件超过这个数目,MySQL 会默默地丢弃多余的条件信息。(由RESIGNAL
添加的条件总是添加的,必要时会淘汰更早的条件以腾出空间。) -
warning_count
表示出现的条件数量。这包括错误、警告和注释。通常,NUMBER
和warning_count
是相同的。但是,当生成的条件数量超过max_error_count
时,warning_count
的值继续增加,而NUMBER
保持在max_error_count
不变,因为不再存储额外的条件信息。 -
error_count
表示出现的错误数量。这包括“not found”和异常条件,但排除警告和注释。像warning_count
一样,它的值也可以超过max_error_count
。 -
如果设置了
sql_notes
系统变量为 0,注释不存储且不增加warning_count
。
示例:如果max_error_count
设置为 10,诊断区可以包含最多 10 个条件区。假设语句引发了 20 个条件,其中 12 个是错误。在这种情况下,诊断区包含前 10 个条件,NUMBER
是 10,warning_count
是 20,error_count
是 12。
修改max_error_count
的值直到下一次尝试修改诊断区。诊断区包含 10 个条件区,max_error_count
设置为 5,这对诊断区的大小或内容没有立即影响。