7.5.9.4 Option Tracker Functions — MySQL 9.2

7.5.9.4 Функции отслеживания опций

Компонент отслеживания опций предоставляет функции, представленные в следующей таблице. Более подробная информация о каждой функции приведена в списке, следующем за таблицей.

Эти функции обеспечивают безопасные интерфейсы для чтения и обновления таблицы mysql_option.option_usage (см. раздел 7.5.9.1 «Таблицы отслеживания опций») и таблицы performance_schema.mysql_option; кроме того, изменения, внесенные с помощью функций, распространяются на вторичные серверы Group Replication, тогда как изменения, внесенные с помощью SQL, нет. По этим причинам для изменения данных об использовании опций всегда следует использовать функции отслеживания опций вместо попыток прямого обновления этих таблиц.

Таблица 7.10 Функции отслеживания опций

Таблица 7.10 Функции отслеживания опций
Имя	Описание
`option_tracker_option_register()`	Зарегистрировать опцию в отслеживателе опций
`option_tracker_option_unregister()`	Отменить регистрацию опции из отслеживателя опций
`option_tracker_usage_get()`	Получить данные об использовании опции, зарегистрированной в отслеживателе опций
`option_tracker_usage_set()`	Установить данные об использовании опции, зарегистрированной в отслеживателе опций

option_tracker_option_register()

Эта функция регистрирует параметр с указанным именем параметра, именем контейнера и значением enabled в системе отслеживания параметров; то есть строка, соответствующая этому параметру, вставляется в таблицу Performance Schema mysql_option.

Синтаксис:

int option_tracker_option_register(
  string option_name,
  string container_name
  int enabled
)

Аргументы:

option_name: Имя параметра. Это строка без учёта регистра. Этот аргумент не может быть нулевым, хотя может быть пустой строкой.
container_name: Имя контейнера. Этот аргумент нечувствителен к регистру и не может быть пустой строкой или нулевым значением.
enabled: 1, если параметр включен, 0, если отключен.

Возвращаемое значение:

0 в случае успеха, ненулевое значение в противном случае. Ненулевое значение обычно 1, но это не гарантируется.

Пример:

mysql> SELECT option_tracker_option_register('Berry Picker', 'component_berry_picker', 0);
+-----------------------------------------------------------------------------+
| option_tracker_option_register('Berry Picker', 'component_berry_picker', 0) |
+-----------------------------------------------------------------------------+
|                                                                           0 |
+-----------------------------------------------------------------------------+

Вы можете проверить, был ли зарегистрирован параметр, запустив запрос к таблице mysql_option следующим образом:

mysql> SELECT * FROM performance_schema.mysql_option WHERE OPTION_NAME='Berry Picker';
+--------------+----------------+------------------------+
| OPTION_NAME  | OPTION_ENABLED | OPTION_CONTAINER       |
+--------------+----------------+------------------------+
| Berry Picker | FALSE          | component_berry_picker |
+--------------+----------------+------------------------+

Для работы этой функции не обязательно, чтобы указанный контейнер существовал.

Вызывающий абонент должен иметь привилегию OPTION_TRACKER_UPDATER; эта привилегия всегда должна предоставляться явно.

Последующие вызовы этой функции не влияют на таблицу mysql_option и возвращают 1, указывая на то, что вызов функции не удался; чтобы изменить статус данного параметра с отключенного на включенный, необходимо отменить его регистрацию с помощью option_tracker_option_unregister(), а затем снова зарегистрировать его, например так:

mysql> SELECT option_tracker_option_register('Berry Picker', 'component_berry_picker', 0);
+-----------------------------------------------------------------------------+
| option_tracker_option_register('Berry Picker', 'component_berry_picker', 0) |
+-----------------------------------------------------------------------------+
|                                                                           0 |
+-----------------------------------------------------------------------------+

mysql> SELECT * FROM performance_schema.mysql_option WHERE OPTION_NAME='Berry Picker';
+--------------+----------------+------------------------+
| OPTION_NAME  | OPTION_ENABLED | OPTION_CONTAINER       |
+--------------+----------------+------------------------+
| Berry Picker | FALSE          | component_berry_picker |
+--------------+----------------+------------------------+

mysql> SELECT option_tracker_option_register('Berry Picker', 'component_berry_picker', 1);
+-----------------------------------------------------------------------------+
| option_tracker_option_register('Berry Picker', 'component_berry_picker', 1) |
+-----------------------------------------------------------------------------+
|                                                                           1 |
+-----------------------------------------------------------------------------+

mysql> SELECT * FROM performance_schema.mysql_option WHERE OPTION_NAME='Berry Picker';
+--------------+----------------+------------------------+
| OPTION_NAME  | OPTION_ENABLED | OPTION_CONTAINER       |
+--------------+----------------+------------------------+
| Berry Picker | FALSE          | component_berry_picker |
+--------------+----------------+------------------------+

mysql> SELECT option_tracker_option_unregister('Berry Picker');
+--------------------------------------------------+
| option_tracker_option_unregister('Berry Picker') |
+--------------------------------------------------+
|                                                0 |
+--------------------------------------------------+

mysql> SELECT * FROM performance_schema.mysql_option WHERE OPTION_NAME='Berry Picker';
Empty set (0.00 sec)

mysql> SELECT option_tracker_option_register('Berry Picker', 'component_berry_picker', 1);
+-----------------------------------------------------------------------------+
| option_tracker_option_register('Berry Picker', 'component_berry_picker', 1) |
+-----------------------------------------------------------------------------+
|                                                                           0 |
+-----------------------------------------------------------------------------+

mysql> SELECT * FROM performance_schema.mysql_option WHERE OPTION_NAME='Berry Picker';
+--------------+----------------+------------------------+
| OPTION_NAME  | OPTION_ENABLED | OPTION_CONTAINER       |
+--------------+----------------+------------------------+
| Berry Picker | TRUE           | component_berry_picker |
+--------------+----------------+------------------------+

Вызовы этой функции не обновляют таблицу mysql_option.option_usage; чтобы добавить или обновить информацию об использовании, используйте option_tracker_usage_set().

option_tracker_option_unregister()

Эта функция отменяет регистрацию параметра, который был ранее зарегистрирован; то есть удаляет соответствующую строку из таблицы mysql_option.

Синтаксис:

int option_tracker_option_unregister(
  string option_name
)

Аргументы:

option_name: Имя параметра, регистрацию которого необходимо отменить. Это строка без учёта регистра, которая не может быть нулевой, но может быть пустой строкой.

Возвращаемое значение:

Пример:

mysql> SELECT * FROM performance_schema.mysql_option
    ->   WHERE OPTION_NAME='Berry Picker';
+--------------+----------------+------------------------+
| OPTION_NAME  | OPTION_ENABLED | OPTION_CONTAINER       |
+--------------+----------------+------------------------+
| Berry Picker | TRUE           | component_berry_picker |
+--------------+----------------+------------------------+

mysql> SELECT option_tracker_option_unregister('Berry Picker');
+--------------------------------------------------+
| option_tracker_option_unregister('berry picker') |
+--------------------------------------------------+
|                                                0 |
+--------------------------------------------------+


mysql> SELECT * FROM performance_schema.mysql_option
    -> WHERE OPTION_NAME='Berry Picker';
Empty set (0.00 sec)

Как отмечалось ранее, имя параметра нечувствительно к регистру, как показано здесь:

mysql> SELECT * FROM performance_schema.mysql_option
    ->   WHERE OPTION_NAME='Berry Picker';
+--------------+----------------+------------------------+
| OPTION_NAME  | OPTION_ENABLED | OPTION_CONTAINER       |
+--------------+----------------+------------------------+
| Berry Picker | TRUE           | component_berry_picker |
+--------------+----------------+------------------------+

mysql> SELECT option_tracker_option_unregister('berry picker');
+--------------------------------------------------+
| option_tracker_option_unregister('berry picker') |
+--------------------------------------------------+
|                                                0 |
+--------------------------------------------------+

mysql> SELECT * FROM performance_schema.mysql_option
    ->   WHERE OPTION_NAME='Berry Picker';
Empty set (0.00 sec)

option_tracker_option_unregister() возвращает ненулевое значение, указывающее на сбой, если в таблице mysql_option не найдена строка, соответствующая имени параметра.

option_tracker_usage_get()

Эта функция возвращает то же значение, что и следующий запрос:

mysql> SELECT USAGE_DATA FROM mysql_option.option_usage
    ->   WHERE OPTION_NAME='JavaScript Stored Program';
+-------------------------------------------------------+
| USAGE_DATA                                            |
+-------------------------------------------------------+
| {"used": "false", "usedDate": "2024-10-17T20:24:41Z"} |
+-------------------------------------------------------+

Синтаксис:

string option_tracker_usage_get(
  option_name
)

Аргументы:

option_name: Строка без учёта регистра.

Возвращаемое значение: Строка в формате JSON. Дополнительные сведения об этом значении см. в описании функции option_tracker_usage_set().

Пример:

mysql> SELECT option_tracker_usage_get('Berry Picker');
+----------------------------------------------------+
| option_tracker_usage_get('Berry Picker')           |
+----------------------------------------------------+
| {"used": true, "usedDate": "2024-10-16T09:14:41Z"} |
+----------------------------------------------------+

option_tracker_usage_set()

Устанавливает данные использования для указанной опции.

Синтаксис:
```
int option_tracker_usage_set(
  string option_name,
  string usage_data
)
```
Аргументы:
- option_name: Имя опции, строка, регистронезависимая. Может быть пустой строкой, но не может быть null.
- usage_data: Данные использования, которые необходимо записать для указанной опции. Должна быть строка в формате JSON, обычно в виде показанном ниже:
```
{
  "used": "boolean"
  "usedDate": "ISO8601 date"
}
```
  Ключ used должен быть true, если опция использовалась в текущей сессии, и false в противном случае. usedDate должен быть строкой со значением даты и времени в формате ISO 8601, например, "2024-10-17T20:24:41Z". Хотя это не обязательно, обычно ожидается, что это текущая дата и время UTC. Вы можете получить это значение, используя UTC_DATE() и UTC_TIME(), аналогично показанному здесь (выделенный текст):
```
SELECT option_tracker_option_set(
  'Berry Picker',
  CONCAT(UTC_DATE(), 'T', UTC_TIME(), 'Z')
);
```
  Рекомендуется использовать форму usage_data с ключами used и usedDate. Можно включать другие ключи и значения в строке JSON, но другие приложения могут их не прочитать, не понять или даже не разрешить.
Тип возвращаемого значения:

Целое число: 0 в случае успеха и ненулевое значение (обычно 1) в противном случае.

Пример:
```
mysql> SELECT option_tracker_usage_set(
    ->   'Berry Picker', '{"used": true, "usedDate": "2024-10-17T20:38:23Z"}');
+------------------------------------------------------------------------------------------------+
| option_tracker_usage_set('Berry Picker', '{"used": true, "usedDate": "2024-10-17T20:38:23Z"}') |
+------------------------------------------------------------------------------------------------+
|                                                                                              0 |
+------------------------------------------------------------------------------------------------+

mysql> SELECT option_tracker_usage_get('Berry Picker');
+----------------------------------------------------+
| option_tracker_usage_get('Berry Picker')           |
+----------------------------------------------------+
| {"used": true, "usedDate": "2024-10-17T20:38:23Z"} |
+----------------------------------------------------+
```

Для каждой из этих функций пользователю, вызывающему функцию, необходимо явно предоставить привилегию OPTION_TRACKER_UPDATER. Это справедливо даже для пользователя MySQL root.