28. Сессионное окружение

В этой главе описываются операторы управления сессионным окружением. Данные SQL операторы работают вне механизма управления транзакциями, изменения выполненные ими вступаю в силу немедленно.

Операторы управления сессионным окружением доступны в том числе и в PSQL коде. Это особенно полезно в ON CONNECT триггерах.

Операторы управления сессионным окружением разбиты на следующие группы:

управления тайм-аутами;
управление пулом внешних соединений;
изменение текущей роли;
управление обработкой типа DECFLOAT;
управление часовым поясом;
сброс сессионного окружения.

28.1. Тайм-ауты

В РЕД Базе Данных существует два вида тайм-аута: тайм-аут простоя соединения и тайм-аут выполнения SQL оператора.

Тайм-аут выполнения SQL оператора

Данная функциональность позволяет автоматически прекратить выполнение SQL оператора, если он выполняется дольше заданного значения тайм-аута.

Данная функция может быть полезна для:

Администраторов баз данных, которые получают инструмент для ограничения времени выполнения тяжёлых запросов, которые потребляют много ресурсов;
Разработчиков приложений, которые могут использовать тайм-ауты SQL операторов при написании и отладке сложных запросов с заранее неизвестным временем выполнения;
Тестеров, которые могут использовать тайм-ауты SQL операторов для обнаружения долго выполняющихся запросов и обеспечения конечного времени выполнения набора тестов.

Эта функциональность работает следующим образом. Когда начинается выполнение оператора (или открывается курсор) РЕД База Данных запускает специальный таймер. Выборка записей (fetch) не сбрасывает таймер. Таймер останавливается, если выполнение SQL оператора закончено или извлечена (fetch) последняя запись.

По истечению тайм-аута:

Если выполнение SQL оператора активно, оно останавливается в заданный момент.
Если SQL оператор не активен в данный момент (например между выборками (fetch)), то он будет помечен как отменённый, следующая выборка (fetch) прервёт выполнение и будет возвращена ошибка.

Значение тайм-аута может быть установлено:

На уровне базы данных. Значение параметра StatementTimeout может быть установлено в firebird.conf (или databases.conf) администратором базы данных. Область действия — все операторы во всех соединениях. Параметр StatementTimeout устанавливает тайм-аут в секундах, по истечении которого выполнение SQL операторов будет отменено. Ноль означает, что тайм-аут не установлен. Значение по умолчанию равно 0.
На уровне соединения. Может быть установлен с использованием API (в миллисекундах) или с помощью SQL оператора SET STATEMENT TIMEOUT. Область действия текущее подключение.
```
SET STATEMENT TIMEOUT <значение> [HOUR | MINUTE | SECOND | MILLISECOND]
```
В качестве параметра выступает значение тайм-аута выполнения SQL операторов в указанных единицах измерения времени. Если единица измерения времени не указано, то по умолчанию значение тайм-аута измеряется в секундах.
На уровне оператора. Может быть установлен с использованием API (в миллисекундах). Область действия — текущий SQL оператор.

Эффективное значение тайм-аута SQL оператора вычисляется каждый раз, когда запускается SQL оператор (открывается курсор), следующим образом:

если тайм-аут не установлен на уровне оператора, будет использовано значение тайм-аута уровня соединения;
если тайм-аут не установлен на уровне соединения, будет использовано значение тайм-аута уровня базы данных;
значение тайм-аута не может быть больше, чем значение установленное на уровне базы данных. Таким образом, значение тайм-аута может перекрываться разработчиком приложения в более низких областях, но оно не может выти за пределы установленные DBA в конфигурации.

Нулевой тайм-аут не обозначает отсутствие тайм-аута, просто в этом случае таймер выполнения оператора не запускается.

Несмотря на то, что тайм-аут выполнения SQL оператора может быть установлен в миллисекундах, абсолютная точность не гарантируется. При высокой нагрузке он может быть менее точным. Единственная гарантия которую может дать РЕД База Данных это то, что тайм-аут не сработает раньше указанного момента. Клиентское приложение может ждать больше времени, чем установленное значение тайм-аута, если движку РЕД Базы Данных необходимо отменить множество действий связанных с отменой оператора.

Тайм-аут выполнения оператора игнорируется для всех внутренних запросов, которые используется движком РЕД Базы Данных. Кроме того, тайм-аут игнорируется для DDL операторов.

Тайм-аут простоя соединения

Данная функциональность позволяет автоматически закрывать пользовательские подключения после периода бездействия. Она может быть использована администраторами баз данных, чтобы принудительно закрывать старые неактивные соединения и освобождать связанные с ними ресурсы. Приложения и инструменты разработчика могут использовать её как замену самодельного контроля за временем жизни подключения.

Рекомендуется (но не обязательно) устанавливать тай-аут простоя в разумное большое значение, например, несколько часов. По умолчанию эта функция отключена.

Эта функциональность работает следующим образом. Когда пользовательский вызов API покидает движок, запускается специальный таймер связанный с текущим подключением. Как только пользовательский вызов входит в движок, таймер ожидания останавливается. Если тайм-аут простоя истечёт движок закроет соединение так как будто произошло асинхронная отмена подключения:

все активные операторы и курсоры закрываются;
все активные транзакции откатываются;
сетевые соединения не закрываются в данный момент. Это позволяет клиентскому приложение получить точный код ошибки при следующем вызове API. Сетевое соединение будет закрыто на стороне сервера после того, как ошибка сообщена, или если клиентская сторона отключится по истечению тайм-аута сети.

Тайм-аут простоя соединения может быть установлен:

На уровне базы данных. Значение параметра ConnectionIdleTimeout может быть установлено в firebird.conf (или databases.conf) администратором базы данных. Область действия — все пользовательские подключения, исключая системные подключения (garbage collector, cache writer, и др.). Параметр ConnectionIdleTimeout устанавливает тайм-аут в минутах, по истечении которого неактивное соединение будет разорвано движком. Ноль означает, что тайм-аут не установлен. Значение по умолчанию равно 0.
На уровне подключения. Может быть установлен с использованием API (в секундах) или с помощью SQL оператора SET SESSION IDLE TIMEOUT. Область действия — все операторы в текущем подключении.
```
SET SESSION IDLE TIMEOUT <значение> [HOUR | MINUTE | SECOND]
```
В качестве параметра выступает значение тайм-аута простоя в указанных единицах измерения времени. Если единица измерения времени не указано, то по умолчанию значение тайм-аута измеряется в минутах.

Эффективное значение тайм-аута простоя вычисляется каждый раз, когда пользовательский вызов API покидает движок, следующим образом:

если тайм-аут не установлен на уровне подключения, будет использовано значение уровня базы данных;
значение тайм-аута не может быть больше, чем значение установленное на уровне базы данных. Таким образом, значение тайм-аута простоя может перекрываться разработчиком приложения для заданного подключения, но оно не может выти за пределы установленные DBA в конфигурации.

Нулевой тайм-аут не обозначает отсутствие тайм-аута, просто в этом случае таймер ожидания не запускается.

Несмотря на то, что тайм-аут простоя может быть установлен в секундах, абсолютная точность не гарантируется. При высокой нагрузке он может быть менее точным. Единственная гарантия которую может дать РЕД База Данных это то, что тайм-аут не сработает раньше указанного момента.

28.2. Пул внешних соединений

Каждое внешнее соединение (созданное оператором EXECUTE STATEMENT ... ON EXTERNAL) при создании связывается с пулом соединений (подробнее см. раздел %s). Данная группа операторов позволяет управлять пулом внешних соединений:

ALTER EXTERNAL CONNECTIONS POOL SET SIZE <размер> — устанавливает максимальное количество бездействующих соединений;
ALTER EXTERNAL CONNECTIONS POOL SET LIFETIME <значение> {SECOND | MINUTE | HOUR} — устанавливает время жизни бездействующих соединений;
ALTER EXTERNAL CONNECTIONS POOL CLEAR ALL — закрывает все бездействующие соединения;
ALTER EXTERNAL CONNECTIONS POOL CLEAR OLDEST — закрывает бездействующие соединения у которых истекло время жизни.

При его подготовке они описываются как DDL операторы, но имеют немедленный эффект: то есть они выполняются немедленно и полностью, не дожидаясь фиксации транзакции. Изменения применяются к экземпляру пула в памяти в текущем процессе РЕД Базы Данных. Поэтому изменение в одном классическом процессе не влияет на другие классические процессы. Изменения не являются постоянными и после перезапуска сервера будет использовать настройки пула из firebird.conf.

Для выполнения операторов данной группы требуется системная привилегия MODIFY_EXT_CONN_POOL (подробнее о системных привелегиях см. CREATE ROLE).

Подробнее см. эти операторы в 35.

28.3. Изменение текущей роли

Данная группа операторов позволяет изменять текущую роль:

SET ROLE <имя роль> — изменение текущей роли;
SET TRUSTED ROLE — включает доступ доверенной роли, при условии, что CURRENT_USER получен с помощью доверительной аутентификации и роль доступна.

Подробнее см. эти операторы в 35.

28.4. Управление часовым поясом и обработкой часовых поясов

Данная группа операторов позволяет управлять часовым поясом:

SET TIME ZONE — изменение часового пояса сеанса;
SET TIME ZONE BIND {NATIVE | LEGACY} — изменение привязки типов с WITH TIME ZONE.

Подробнее см. эти операторы в 35.

28.5. Управление обработкой DECFLOAT

Для изменения режима округления для типа DECFLOAT создан оператор SET DECFLOAT ROUND <режим>.

Поддерживаются следующие режимы округления совместимые со стандартом IEEE: CEILING, UP, HALF_UP, HALF_EVEN, HALF_DOWN, DOWN, FLOOR, REROUND.

Подробнее см. эти операторы в 35.

28.6. Сброс сессионного окружения

Оператор ALTER SESSION RESET сбрасывает сеансовое окружение (подключения) к исходному состоянию. Эта функциональность полезна, если сеанс используется повторно, вместо того, чтобы производить отключение/подключение.

ALTER SESSION RESET

Данный оператор делает следующее:

сбрасывает установленные параметры DECFLOAT (BIND, TRAP и ROUND) в значения по умолчанию;
сбрасывает тайм-ауты сессии и оператора в 0;
удаляет все контекстные переменные из пространства имён USER_SESSION;
очищает содержимое всех используемых глобальных таблиц уровня соединения ( COMMIT PRESERVE ROWS);
сбрасывает роль в значение переданное в DPB (указанное при подключении) и очищает кэш привелегий (если роль была изменена с помощью оператора SET ROLE);
текущая активная транзакция откатывается и стартуется новая с теми же параметрами, после рестарта.

Предупреждение

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

Предупреждение

Если в текущей сессии активны другие транзакции, то будет выдана ошибка. При проверке транзакций перед сбросом сессии подготовленные 2PC транзакции игнорируются.