27.3.6.1 Session Object — MySQL 9.2

27.3.6.1 Объект сеанса

Объект Session всегда доступен как свойство session глобального объекта. У объекта Session есть методы, перечисленные здесь:

getOption(String name): Получает значение параметра оператора name. Возвращает строку или значение true/false в зависимости от типа параметра.
prepare(String sql, {passResultToClient: Bool, charsetName: String}): Включает выполнение подготовленных операторов; принимает SQL-запрос и возвращает объект PreparedStatement.

Вызов этого метода эквивалентен выполнению оператора PREPARE в клиенте mysql.
quoteName(String name): Возвращает name после экранирования.
runSql(String query[[, Array statementParameters], Options options]): Выполняет запрос с указанными параметрами и (необязательным) списком параметров оператора; возвращает SqlResult.
setOptions(Object options): Устанавливает значения по умолчанию для параметров оператора. Параметры, не указанные явно, принимают значения по умолчанию.
sql(String sql, {passResultToClient: Bool, charsetName: String, integerType: IntegerType}): Выполняет простой SQL-запрос. Также может использоваться для предоставления атрибутов, перезаписывающих значения passResultlToClient и charsetName, заданные в сеансе. Возвращает объект SqlExecute.

IntegerType представляет собой JSON-пару ключ-значение, где ключ — IntegerType, а возможные значения и их эффекты приведены ниже:
- mysql.IntegerType.BIGINT: Преобразует все целочисленные значения MySQL в JavaScript BigInt.
- mysql.IntegerType.STRING: Преобразует все целочисленные значения MySQL в JavaScript String.
- mysql.IntegerType.UNSAFE_BIGINT: Если значение MySQL безопасно, преобразует его в JavaScript Number; в противном случае преобразует в JavaScript BigInt. Если значение безопасно, преобразует в JavaScript Number; в противном случае преобразует в JavaScript String. Это поведение по умолчанию, если не указано иное правило.
- mysql.IntegerType.UNSAFE_STRING: Если значение MySQL безопасно, преобразует его в JavaScript Number; в противном случае преобразует в JavaScript String. Это поведение по умолчанию, если не указано иное правило.
Правило, установленное этим значением, определяет, как целочисленные значения MySQL преобразуются в JavaScript этим SQL-запросом. Их имена (без ссылок на объекты) соответствуют именам, используемым с ключом integer_type в mle_set_session_state(). Поведение по умолчанию эквивалентно установке mysql.IntegerType.UNSAFE_STRING или вызову mle_set_session_state('{"integer_type":"STRING"}').

Этот параметр также можно установить для данного оператора, используя runSQL() или prepare().

Транзакционные функции JavaScript, поддерживаемые в MySQL 9.2.0 и более поздних версиях, также являются методами Session. См. Раздел 27.3.6.9, «JavaScript Transaction API» для описаний и примеров.

Доступ к переменным сеанса из JavaScript

Начиная с MySQL 9.2.0, вы можете получить доступ к переменным сеанса MySQL как к свойствам объекта Session, как показано в этом примере:

mysql> SET @myvar = 27;
Query OK, 0 rows affected (0.00 sec)

mysql> CREATE PROCEDURE get_session_var() LANGUAGE JAVASCRIPT
    -> AS $$
    $>     console.clear()
    $>     let the_var = session.myvar
    $>
    $>     console.log("the_var: " + the_var)
    $>     console.log("typeof the_var: " + typeof the_var)
    $> $$;
Query OK, 0 rows affected (0.01 sec)

mysql> CALL get_session_var();
Query OK, 0 rows affected (0.01 sec)

mysql> SELECT mle_session_state("stdout")\G
*************************** 1. row ***************************
mle_session_state("stdout"): the_var: 27
typeof the_var: number

mysql> SET @myvar = "Something that is not 27";
Query OK, 0 rows affected (0.00 sec)

mysql> CALL get_session_var();
Query OK, 0 rows affected (0.00 sec)

mysql> SELECT mle_session_state("stdout")\G
*************************** 1. row ***************************
mle_session_state("stdout"): the_var: Something that is not 27
typeof the_var: string

1 row in set (0.00 sec)

Вы также можете задавать переменные сеанса, обращаясь к ним таким же образом, как показано здесь:

mysql> CREATE PROCEDURE set_session_var(IN x INT) LANGUAGE JAVASCRIPT
    -> AS $$
    $>   session.myvar = x
    $> $$;
Query OK, 0 rows affected (0.01 sec)

mysql> CALL set_session_var(72);
Query OK, 0 rows affected (0.00 sec)

mysql> SELECT @myvar;
+--------+
| @myvar |
+--------+
|     72 |
+--------+
1 row in set (0.00 sec)

Переменные сеанса, доступные как свойства Session в JavaScript, создаются автоматически, если они еще не существуют, как показано в этом примере:

mysql> CREATE PROCEDURE set_any_var(IN name VARCHAR, IN val INT)
    ->   LANGUAGE JAVASCRIPT
    -> AS $$
    $>   session[name] = val
    $> $$;
Query OK, 0 rows affected (0.00 sec)

mysql> SELECT @yourvar;
+--------------------+
| @yourvar           |
+--------------------+
| NULL               |
+--------------------+
1 row in set (0.00 sec)

mysql> CALL set_any_var("myvar", 25);
Query OK, 0 rows affected (0.01 sec)

mysql> CALL set_any_var("yourvar", 100);
Query OK, 0 rows affected (0.00 sec)

mysql> SELECT @myvar, @yourvar;
+--------+----------+
| @myvar | @yourvar |
+--------+----------+
|     25 |      100 |
+--------+----------+
1 row in set (0.00 sec)

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

Тип MySQL	Тип JavaScript	Комментарии
`NULL`	`null`	-
`BIGINT`	`Number`, `String` или `BigInt`	Зависит от значения параметра `session.sql()` метода `integerType`
`DECIMAL`	-	Ошибка: Неподдерживаемый тип
`DOUBLE`	`Number`	-
Бинарная строка	`Uint8Array`	-
Строка	`String`	-

Правила преобразования типов из JavaScript-переменных в переменные сеанса MySQL показаны в следующей таблице:

Тип JavaScript	Тип MySQL	Комментарий
`null` или `undefined`	`NULL`	-
`Boolean`	`BIGINT`	-
`Number`	`BIGINT`, `DECIMAL` или `DOUBLE`	-
`Infinity`, `NaN` или `Symbol`	-	Ошибка: Тип не может быть использован для переменных сеанса
`String`	строка	-
`BigInt`	`BIGINT`	-
`TypedArray` или `Float32Array`	`BINARY`	-
`Object`	строка	-
`Array`	строка	-