27.3.4 JavaScript Stored Program Data Types and Argument Handling — MySQL 9.2

27.3.4 Типы данных хранимых программ JavaScript и обработка аргументов

Большинство типов данных MySQL поддерживаются для входных и выходных аргументов хранимых программ MLE, а также для типов возвращаемых данных. Типы данных перечислены здесь:

Целые числа: Поддерживаются все варианты и псевдонимы целых типов данных MySQL, включая TINYINT, SMALLINT, MEDIUMINT, INT и BIGINT.

SIGNED и UNSIGNED поддерживаются для всех этих типов.

BOOL и SERIAL также поддерживаются и обрабатываются как целые типы.
Строки: Поддерживаются типы строк CHAR, VARCHAR, TEXT и BLOB.

Эти типы поддерживаются так же, как и в сервере MySQL, с следующими исключениями:
1. Аргументы и возвращаемые значения строкового типа могут использовать наборы символов utf8mb4 или двоичных символов; использование других наборов символов для этих целей приводит к ошибке. Это ограничение относится к объявлениям аргументов и типов возвращаемых значений; сервер пытается преобразовать значения аргументов значений используя другие наборы символов к utfmb4, когда это необходимо, как и в хранимых программах SQL.
2. Максимальная поддерживаемая длина значения LONGTEXT составляет 1073741799 (2³⁰ - 2⁴ - 2³ - 1) символов; для LONGBLOB максимальная поддерживаемая длина составляет 2147483639 (2³¹ - 2⁸ - 1).
Поддержка типов BLOB включает поддержку BINARY и VARBINARY.

Тип данных MySQL JSON также поддерживается.
Числа с плавающей точкой: FLOAT и DOUBLE поддерживаются вместе с их псевдонимами. REAL также рассматривается как число с плавающей точкой, но UNSIGNED FLOAT и UNSIGNED DOUBLE устарели в MySQL и не поддерживаются MLE.
Временные типы: DATE, DATETIME и TIMESTAMP поддерживаются и преобразуются в значения JavaScript Date. Значения TIME рассматриваются как строки; значения YEAR рассматриваются как числа.

В первый раз при выполнении хранимой процедуры JavaScript, она ассоциируется с текущей часовой зоной сеанса MySQL, и эта часовая зона продолжает использоваться хранимой программой, даже если часовая зона сеанса MySQL изменяется одновременно, на протяжении всего сеанса компонента MLE или до вызова mle_session_reset(). Более подробная информация находится в Поддержка часовых поясов в этой секции.
VECTOR поддерживается в MySQL 9.1 и более поздних версиях.

Входные аргументы (параметры IN и INOUT) автоматически преобразуются в типы JavaScript на основе отображения, показанного в следующей таблице:

Таблица 27.1 Преобразование типов: MySQL в JavaScript

Таблица 27.1 Преобразование типов: MySQL в JavaScript
Тип MySQL	Тип JavaScript
`TINYINT`, `SMALLINT`, `MEDIUMINT`, `INT`, `BOOL`, `BIGINT` или `SERIAL`	Если безопасно: `Number`; в противном случае: `String`
`FLOAT` или `DOUBLE`	`Number`
`CHAR`, `VARCHAR`, `TINYTEXT`, `TEXT`, `MEDIUMTEXT` или `LONGTEXT`	`String`
`TINYBLOB`, `BLOB`, `MEDIUMBLOB`, `LONGBLOB`, `BINARY` или `VARBINARY`	`Uint8Array`
`DATE`, `DATETIME` или `TIMESTAMP`	`Date`
`TIME`	`String`
`YEAR`	`Number`
`VECTOR`	`Float32Array`

Преобразование в или из целого числа MySQL, значение которого лежит вне диапазона -(2⁵³-1) (-9007199254740991) до 2⁵³-1 (9007199254740991) является потерей данных. Способ преобразования целых чисел MySQL в JavaScript можно изменить для текущего сеанса с помощью mle_set_session_state(); поведение по умолчанию эквивалентно вызову этой функции с использованием UNSAFE_STRING в качестве значения для integer_type. Подробнее см. описание этой функции.

SQL NULL поддерживается для всех перечисленных типов и преобразуется в JavaScript null по мере необходимости.

JavaScript (в отличие от SQL) — язык с динамической типизацией, что означает, что типы возвращаемых значений известны только во время выполнения. Возвращаемые значения JavaScript и выходные аргументы (параметры OUT и INOUT) автоматически преобразуются обратно в ожидаемый тип MySQL на основе отображений, показанных в следующей таблице:

Таблица 27.2 Преобразование типов: JavaScript в MySQL

Таблица 27.2 Преобразование типов: JavaScript в MySQL
Тип данных JavaScript	Тип MySQL `TINYINT`, `SMALLINT`, `MEDIUMINT`, `INT`, `BIGINT`, `BOOLEAN` или `SERIAL`	Тип MySQL `CHAR` или `VARCHAR`	Тип MySQL `FLOAT` или `DOUBLE`	Тип MySQL `TINYTEXT`, `TEXT`, `MEDIUMTEXT` или `LONGTEXT`	Тип MySQL `TINYBLOB`, `BLOB`, `MEDIUMBLOB`, `LONGBLOB`, `BINARY`, `VARBINARY`	Тип MySQL `VECTOR`
`Boolean`	Приведение к типу `Integer`	Преобразование в `String`; проверка, находится ли длина результата в ожидаемом диапазоне	Приведение к типу `Float`	Если JavaScript `Boolean` `true`: преобразовать в «true»; если JavaScript `Boolean` `false`: преобразовать в «false»	Ошибка	Ошибка
`Number`	Округление значения до `Integer`; проверка, не выходит ли значение за пределы диапазона ^[a] ^[b] ^[c]	Преобразование в `String`; проверка, находится ли длина результата в ожидаемом диапазоне	Сохранение значения; проверка, не выходит ли оно за пределы диапазона ^[a] ^[b]	Преобразование в `String`; проверка, находится ли длина результата в ожидаемом диапазоне	Ошибка	Ошибка
`BigInteger`	Сохранение значения; проверка, не выходит ли оно за пределы диапазона ^[a] ^[b]	Преобразование в `String`; проверка, находится ли длина результата в ожидаемом диапазоне	Приведение к типу `Float`; проверка, не выходит ли результат за пределы диапазона ^[d]	Преобразование в `String`; проверка, находится ли длина результата в ожидаемом диапазоне	Ошибка	Ошибка
`String`	Парсинг как число и округление до `Integer`; проверка на выход за пределы диапазона	Сохранение значения; проверка, находится ли длина в допустимом диапазоне	Парсинг значения в `Float`; проверка на выход за пределы диапазона ^[d]	Использование существующего строкового значения; проверка, находится ли длина строки в ожидаемом диапазоне	Ошибка	Ошибка
`Symbol` или `Object`	Возбуждение ошибки некорректного преобразования типа	Преобразование в `String`; проверка, находится ли длина результата в ожидаемом диапазоне	Возбуждение ошибки некорректного преобразования типа	Преобразование в `String`; проверка, находится ли длина результата в ожидаемом диапазоне ^[e]	Ошибка	Ошибка
Тип `Array`	Возбуждение ошибки некорректного преобразования типа	Преобразование в `String`; проверка, находится ли длина результата в ожидаемом диапазоне	Возбуждение ошибки некорректного преобразования типа	Преобразование в `String`; проверка, находится ли длина результата в ожидаемом диапазоне ^[e]	Преобразование в массив байтов; проверка, находится ли результат в ожидаемом размере ^[f]	Обработка как `Float32Array`; преобразование в массив байтов, проверка соответствия ожидаемому размеру поля `VECTOR`
`null` или `undefined`	`NULL`	`NULL`	`NULL`	`NULL`	`NULL`	`NULL`

^[a] JavaScript Infinity и -Infinity рассматриваются как значения, выходящие за пределы диапазона.

^[b] JavaScript NaN вызывает ошибку некорректного преобразования типа.

^[c] Это делается с помощью Math.round().

^[d] Нечисловое значение вызывает ошибку некорректного преобразования типа.

^[e] Максимальная поддерживаемая длина строки — 1073741799

^[f] Максимальная поддерживаемая длина BLOB — 2147483639

Таблица 27.3 Преобразование типов: JavaScript даты в MySQL

Таблица 27.3 Преобразование типов: JavaScript даты в MySQL
Тип JavaScript	Тип MySQL `DATE`	Тип MySQL `DATETIME`, `TIMESTAMP`	Тип MySQL YEAR
`null` или `undefined`	`NULL`	`NULL`	`NULL`
`Date`	Сохранение значения без изменений, округление любой временной части до ближайшей секунды.	Сохранение значения без изменений.	Извлечение года из `Date`
Тип, преобразуемый в JavaScript `Date` (форматированная строка)	Приведение значения к JavaScript `Date` и обработка соответствующим образом	Приведение значения к JavaScript `Date` и обработка соответствующим образом	Если значение содержит 4-значный год, использовать его.
Тип, не преобразуемый в JavaScript `Date`	Ошибка некорректного преобразования типа	Ошибка некорректного преобразования типа	Если значение содержит 4-значный год, использовать его.

Передача нулевой даты MySQL (00-00-0000) или нулевого значения даты (например, 00-01-2023) приводит к созданию экземпляра Invalid Date типа Date. При передаче некорректной даты MySQL (например, 31 февраля), MLE вызывает конструктор JavaScript Date с некорректными значениями отдельных компонентов даты и времени.

Тип MySQL TIME обрабатывается как строка и валидируется внутри MySQL. Подробнее см. Раздел 13.2.3, «Тип TIME».

Таблица 27.4 Преобразование типов: MySQL JSON в JavaScript

Таблица 27.4 Преобразование типов: MySQL JSON в JavaScript
Тип MySQL JSON	Тип JavaScript
`NULL`, `JSON NULL`	`null`
`JSON OBJECT`	`Object`
`JSON ARRAY`	`Array`
`JSON BOOLEAN`	`Boolean`
`JSON INTEGER`, `JSON DOUBLE`, `JSON DECIMAL`	`Number`
`JSON STRING`	`String` ^[a]
`JSON DATETIME`, `JSON DATE`, `JSON TIME`	`String`
`JSON BLOB`, `JSON OPAQUE`	`String`

^[a] Строка MySQL JSON, при преобразовании в строку Javascript, становится не заключенной в кавычки.

Таблица 27.5 Преобразование типов: JavaScript в MySQL JSON

Таблица 27.5 Преобразование типов: JavaScript в MySQL JSON
Тип JavaScript	Тип MySQL JSON
`null`, `undefined`	`NULL`
`Boolean`	Ошибка ^[a]
`Number`	Ошибка ^[a]
`String`	Может быть распарсен как JSON: JSON-строка, JSON-объект или JSON-массив Не может быть распарсен как JSON: Ошибка `'null'`: JSON `null`
`BigInt`	Ошибка ^[b]
`Object`	JSON-объект или ошибка (см. текст после таблицы)
`Array`	JSON-массив
`Symbol`	Внутри объекта: проигнорировано Внутри массива: JSON `null` Скалярное значение: Ошибка

^[a] Значение внутри контейнера, такого как JSON-массив или JSON-объект, преобразуется (возможна потеря точности для Number значений). Скалярное значение вызывает ошибку.

^[b] JavaScript BigInt значения не могут быть преобразованы в MySQL JSON; попытка такого преобразования всегда вызывает ошибку, независимо от того, находится ли значение внутри контейнера или нет.

Возможно или нет преобразование JavaScript Object в MySQL JSON, зависит от того, как toJSON() реализовано для данного объекта. Ниже приведены некоторые примеры:

Метод toJSON() класса JavaScript Date преобразует Date в строку с неверной синтаксической структурой JSON, что приводит к ошибке преобразования.
Для класса Set, toJSON() возвращает "{}", что является корректной JSON-строкой.
Для объектов, похожих на JSON, toJSON() возвращает корректную JSON-строку.

Преобразование из и в MySQL ENUM и SET. Поддержка типов MySQL ENUM и SET для аргументов JavaScript-программ доступна в MySQL 9.2.0 и более поздних версиях. ENUM преобразуется в JavaScript String; SET преобразуется в JavaScript Set объект, как показано в следующей таблице:

Таблица 27.6 Преобразование типов: MySQL ENUM и SET в JavaScript

Таблица 27.6 Преобразование типов: MySQL ENUM и SET в JavaScript
Тип MySQL	Тип JavaScript
`ENUM`	`String`
`SET`	`Set`

В следующей таблице показаны правила преобразования типа JavaScript в тип MySQL ENUM или SET:

Таблица 27.7 Преобразование типов: JavaScript в MySQL ENUM и SET

Таблица 27.7 Преобразование типов: JavaScript в MySQL ENUM и SET
Тип JavaScript	В MySQL `ENUM`	В MySQL `SET`
Строка	Сохранить значение; проверить, является ли строка допустимым значением `ENUM`	Сохранить значение; проверить, является ли строка допустимым значением `SET`
`null`, `undefined`	`NULL`	`NULL`
`Set`	Ошибка	Преобразовать в строку, разделенную запятыми; проверить, является ли строка допустимым значением `SET`
Любой другой тип	Ошибка	Ошибка

Дополнительные заметки

Все значения, используемые в или для ENUM или SET значений или их JavaScript-эквивалентов, должны использовать набор символов utf8mb4. См. Раздел 12.9.1, «Набор символов utf8mb4 (4-байтовое кодирование UTF-8 Unicode)» для получения дополнительной информации.
Режим сервера SQL может влиять на то, как обрабатывается неверное значение JavaScript при попытке вставки его в столбец ENUM или SET. В режиме строгости (по умолчанию) неверное значение вызывает ошибку; в противном случае вставляется пустая строка с предупреждением. См. Раздел 7.1.11, «Режимы сервера SQL».

Поддержка часовых поясов. JavaScript-хранимые программы используют часовой пояс MySQL, действующий в момент первого вызова. Этот часовой пояс остается в силе для этой хранимой программы на протяжении всего сеанса.

Изменение часового пояса сеанса MySQL не автоматически отражается в хранимых программах, которые уже использовались и кэшируются. Чтобы заставить их использовать новый часовой пояс, вызовите mle_session_reset() для очистки кэша; после этого хранимые программы будут использовать новый часовой пояс.

Поддерживаемые типы часовых поясов перечислены здесь:

Смещения часовых поясов от UTC, такие как +11:00 или -07:15.
Часовые пояса, определённые в базе данных часовых поясов IANA, поддерживаются за исключением конфигураций, использующих високосные секунды. Например, Pacific/Nauru, Japan и MET поддерживаются, в то время как leap/Pacific/Nauru и right/Pacific/Nauru нет.

Проверка диапазонов и проверка преобразования неверного типа выполняются после выполнения хранимой программы. Преобразование выполняется внутри JavaScript с помощью конструкторов типов, таких как Number() и String(); округление до Integer выполняется с помощью Math.round().

Входной аргумент (IN или INOUT параметр), указанный в определении хранимой JavaScript-программы, доступен внутри тела процедуры с тем же идентификатором аргумента. Выходные аргументы (INOUT и OUT параметры) также доступны в хранимых процедурах JavaScript. Тот же идентификатор аргумента может быть использован для установки значения с помощью оператора присваивания JavaScript (=). Как и в случае с аргументами SQL-хранимых процедур OUT, начальное значение устанавливается в JavaScript null.

Внимание

Не следует переопределять аргументы программы с помощью let, var или const внутри хранимых JavaScript-программ. Это превращает их в переменные, локальные для программы, и делает недоступными любые значения, передаваемые в программу с использованием параметров с тем же именем.

Пример:

mysql> CREATE FUNCTION myfunc(x INT)
    ->   RETURNS INT LANGUAGE JAVASCRIPT AS
    -> $$
    $>   var x
    $>
    $>   return 2*x
    $> $$
    -> ;
Query OK, 0 rows affected (0.03 sec)

mysql> SELECT myfunc(10);
ERROR 6000 (HY000): MLE-Type> Cannot convert value 'NaN' to INT
from MLE in 'myfunc(10)'

Оператор JavaScript return должен использоваться для возвращения скалярных значений в хранимых функциях. В хранимых процедурах этот оператор не возвращает значение и просто завершает блок кода (это может или не может также завершить процедуру в зависимости от потока программы). return не может быть использован для установки значений аргументов хранимых процедур OUT или INOUT; они должны быть установлены явно в рамках процедуры.

Подробная информация о доступе к хранимым процедурам и функциям MySQL из хранимых JavaScript-процедур представлена в Разделе 27.3.6.8, «API хранимых процедур».