13.6.7.7 The MySQL Diagnostics Area — MySQL 5.7

13.6.7.7 Область диагностики MySQL

SQL-запросы генерируют диагностическую информацию, которая заполняет область диагностики. Стандартный SQL имеет стек области диагностики, содержащий область диагностики для каждого вложенного контекста выполнения. Стандартный SQL также поддерживает GET STACKED DIAGNOSTICS синтаксис для ссылки на вторую область диагностики во время выполнения обработчика условий. MySQL поддерживает ключевое слово STACKED начиная с MySQL 5.7. До этого MySQL не поддерживает STACKED; существует единственная область диагностики, содержащая информацию от последнего запроса, который в неё записал.

Следующее обсуждение описывает структуру области диагностики в 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() (см. Раздел 12.15, «Функции информации»).

Часть информации об условиях в области диагностики содержит область условий для каждого условия. Области условий пронумерованы от 1 до значения элемента условия запроса NUMBER. Если значение NUMBER равно 0, областей условий нет.

Каждая область условий содержит элементы из следующего списка. Все элементы — стандартные SQL, за исключением 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. Это значение взято из аргумента SQLSTATE запроса SIGNAL.

Запрос 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 сгенерировала одно условие, поэтому 1 — единственный допустимый номер условия для GET DIAGNOSTICS в данный момент. Следующая инструкция использует номер условия 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 передает информацию об условии ошибки, которая доступна во время выполнения обработчика условия в составном операторе внутри хранимой программы. RESIGNAL может изменить некоторую или всю информацию перед передачей, изменяя стек диагностики, как описано в Раздел 13.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 указывает количество возникших ошибок. Это значение включает условия «не найдено» и исключения, но исключает предупреждения и заметки. Как и 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, это не оказывает непосредственного влияния на размер или содержимое области диагностики.