# Управление выполнением запросов к БД

Механизм управления выполнением запросов к БД позволяет централизованно настраивать, через какую БД сервер приложений выполняет прикладные запросы. Настройка выполняется в интерфейсе Global ERP и не требует изменения прикладного кода.

Механизм нужен, чтобы направлять разные типы запросов к подходящим БД. Например, запросы чтения могут выполняться через реплики, а запросы изменения данных — через основную БД. Это позволяет гибко управлять выполнением запросов для разных объектов, ролей, профилей и групп пользователей.

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

Путь: `Настройка системы > Настройки и сервисы > Дополнительно > Настройка пулов подключений к БД`.

## Интерфейс настройки

При открытии интерфейса доступны 4 основные закладки:

- **Пулы подключений**;
- **Настройки приоритетов**;
- **Группы объектов**;
- **Анализ**.

![pool](/070_addition//img/pool.png)

### Пулы подключений

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

В таблице пулов отображаются:

| Поле | Описание |
|---|---|
| **Код** | Системное имя пула, подгруженное из конфигурации сервера приложений. |
| **Наименование** | Отображаемое название пула. |
| **Описание** | Дополнительное описание назначения пула. |
| **Приоритет** | Порядок выбора пула при наличии нескольких подходящих правил. Чем больше числовое значение, тем выше приоритет. |
| **Реплика** | Признак того, что пул подключается к реплике БД. |

Детальная настройка пулов описана в разделе [Импорт пулов из конфигурации](#импорт-пулов-из-конфигурации).

### Настройки приоритетов

Закладка **Настройки приоритетов** используется для настройки правил применения пула подключения. Здесь задаются условия, при которых запросы должны выполняться через определенный пул.

Настройка выполняется в таблице правил.

| Поле | Описание |
|---|---|
| **Пул подключений** | Пул, через который должны выполняться запросы для выбранной группы объектов и условий по пользователям. Пулы отображаются на закладке **Пулы подключений** и импортируются из конфигурации сервера приложений. |
| **Группа QoS** | Группа объектов, для которых применяется правило. Группы создаются на закладке **Группы объектов**. |
| **Ограничения по пользователю** | Условия применения правила по пользователям. Включают поля **Тип** и **Значение**. |
| **Тип** | Определяет, по какому пользовательскому признаку применяется правило. Возможные варианты: **Роль**, **Профиль**, **Группа пользователей** или **Без ограничений**. Если ограничение по пользователям не требуется, выберите **Без ограничений**. |
| **Значение** | Конкретное значение ограничения. Если выбран тип **Роль**, указывается роль. Если выбран тип **Профиль**, указывается профиль. Если выбран тип **Группа пользователей**, указывается группа пользователей. Если выбран вариант **Без ограничений**, поле не заполняется. |
| **Не используется** | Признак отключения правила без удаления настройки. |
| **Дата окончания использования** | Дата, после которой правило перестает применяться. |

Детальная настройка правил описана в разделе [Настройка правил применения пулов](#настройка-правил-применения-пулов).

### Группы объектов

Закладка **Группы объектов** используется для создания групп объектов, от которых выполняются запросы к БД.

Группы объектов отображаются в виде таблицы.

| Поле | Описание |
|---|---|
| **Код** | Системное имя группы. |
| **Наименование** | Отображаемое название группы. |
| **Описание** | Дополнительное описание назначения группы. |
| **Не используется** | Признак отключения группы без удаления настройки. |

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

Детальная настройка групп объектов описана в разделе [Настройка групп объектов](#настройка-групп-объектов).

### Анализ

Закладка **Анализ** используется для проверки настроенных правил и подбора подходящего пула. Это инструмент диагностики, который помогает понять, какой пул будет применен для конкретного объекта или выборки.

На закладке можно выполнить проверку:

- по выборке;
- по объекту;
- с учетом признака реплики;
- с учетом фильтра по пользователю.

Для проверки заполните параметры анализа и нажмите **Найти подходящий пул**. Система определит, какие правила подходят под указанный контекст, и покажет доступные пулы подключения.

## Общий порядок настройки

Для настройки механизма выполните действия по порядку:

1. Задайте пулы подключений к БД в конфигурации сервера приложений.
2. Перезапустите сервер приложений.
3. Откройте интерфейс `Настройка системы > Настройки и сервисы > Дополнительно > Настройка пулов подключений к БД`.
4. На закладке **Пулы подключений** выполните операцию **Импортировать пулы**.
5. Проверьте список пулов, заполните наименования, описания, приоритеты и признак **Реплика**.
6. На закладке **Группы объектов** создайте группы и добавьте в них выборки, печатные формы или фоновые задания.
7. На закладке **Настройки приоритетов** создайте правило применения пула.
8. Укажите пул подключений, группу QoS и ограничения по пользователю.
9. При необходимости заполните признаки ограничения использования правила.
10. На закладке **Анализ** проверьте, какой пул подбирается для нужной выборки, объекта и пользователя.

Ниже приведена общая структура настройки механизма:

~~~
[Пулы подключений к БД]
        │
        ├── [Группы объектов QoS]
        │        │
        │        └── [Объекты группы]
        │
        └── [Правила применения пула]
                 │
                 ├── условия по пользователям
                 ├── группа объектов
                 └── пул подключения
~~~

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

При выполнении запроса система определяет объект, пользователя и тип операции. После этого выбирает подходящее правило и пул подключения.

## Настройка механизма

### Настройка пулов в конфигурации

Пулы подключений к БД задаются в конфигурации сервера приложений в разделе `Special Pools`. В структуре конфигурации настройка находится по пути `databases > database > specialConnectionPools > pool`.

После настройки в конфигурации пулы импортируются в интерфейс Global ERP и становятся доступны для выбора в правилах применения пулов.

После изменения состава пулов требуется перезапуск сервера приложений. Динамическое добавление, удаление и перечитывание пулов без перезапуска не поддерживается.

Детальное описание настройки пула приведено в справочнике [Pool](https://docs.global-system.ru/as/dev/reference/configuration/global3_config_xsd/configuration/databases/database/specialconnectionpools/Pool.html#Configuration.Databases.Database.SpecialConnectionPools.Pool).

### Импорт пулов из конфигурации

После настройки пулов в конфигурации сервера приложений импортируйте их в интерфейс Global ERP.

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

После импорта дозаполните прикладные параметры каждого пула:

- наименование;
- описание;
- приоритет;
- признак **Реплика**.

Признак **Реплика** указывает, что пул ведет не на master-БД, а на реплику БД. Подробные правила использования master-БД и реплик описаны в разделе [Работа с master-БД и репликами](#работа-с-master-бд-и-репликами).

Приоритет пула используется, если для одного объекта подходит несколько правил. Правила применения приоритетов описаны в разделе [Приоритеты](#приоритеты).

### Настройка групп объектов

Группа объектов определяет набор объектов, для которых можно назначить общее правило применения пула подключения.

Для настройки группы объектов:

1. Откройте закладку **Группы объектов**.
2. Создайте группу объектов.
3. Заполните системное имя, наименование и описание группы.
4. Добавьте в группу один или несколько объектов.
5. Сохраните настройку.

В группу необходимо добавить хотя бы один объект, иначе правило, связанное с этой группой, не будет применяться к запросам.

В состав группы можно добавить:

- выборку;
- печатную форму;
- фоновое задание.

В одну группу можно добавить объекты разных типов. Например, в одной группе могут быть указаны выборки, печатные формы и фоновые задания, если для них нужно применять одно правило применения пула.

Правила использования master-БД и реплик зависят от того, для какой операции или события выполняется запрос. Подробно эта логика описана в разделе [Работа с master-БД и репликами](#работа-с-master-бд-и-репликами).

**Выборки и отображения**  
Для выборок рекомендуется указывать не только системное имя выборки, но и отображение, если правило должно применяться к конкретному варианту отображения данных. Это позволяет направлять запросы конкретного отображения через отдельный пул и не менять поведение других отображений той же выборки.

Если в качестве отображения указано `Default`, группа будет применяться ко всем отображениям выбранной выборки.

**Печатные формы и отчеты**  
Печатные формы и отчеты можно включать в группы объектов, если для них нужно назначить отдельные правила применения пулов. Это полезно для массового или ресурсоемкого построения отчетов и печатных форм.

**Фоновые задания**  
Фоновые задания можно включать в группы объектов, если для них нужно назначить отдельный пул подключения. Если внутри фонового задания формируется печатная форма, для запросов печатной формы может применяться отдельное правило применения пула, настроенное для этой печатной формы.

~~~{note}
- Группы объектов являются линейными. Иерархия групп объектов не поддерживается.
- Один объект не должен дублироваться внутри одной группы. Если для одного объекта нужно задать несколько вариантов управления запросами, настройка выполняется через разные правила.
~~~

### Настройка правил применения пулов

Правило применения пула связывает группу объектов, условия применения по пользователям и пул подключения к БД.

Для настройки правила:

1. Откройте закладку **Настройки приоритетов**.
2. Создайте правило.
3. Укажите пул подключения.
4. Укажите группу QoS.
5. В колонке **Ограничения по пользователю** укажите тип ограничения:
   - **Роль**;
   - **Профиль**;
   - **Группа пользователей**;
   - **Без ограничений**.
6. Заполните поле **Значение**, если выбран тип **Роль**, **Профиль** или **Группа пользователей**.
7. При необходимости заполните признаки ограничения использования правила.
8. Сохраните правило.
9. Проверьте результат на закладке **Анализ**.

В правиле обязательно указывается пул подключения. Группа QoS и ограничения по пользователю определяют область действия правила. Если группа QoS не указана, правило применяется ко всем объектам. Если правило должно действовать для всех пользователей, в поле **Тип** выберите **Без ограничений** и не заполняйте поле **Значение**.

Примеры настройки правил:

| Настройка правила | Как применяется |
|---|---|
| Указана группа объектов и ограничение по роли, профилю или группе пользователей | Правило применяется только для указанной группы объектов и указанного ограничения по пользователям. |
| Указана группа объектов и выбран вариант **Без ограничений** | Правило применяется для указанной группы объектов и всех пользователей. |
| Группа объектов не указана, задано ограничение по роли, профилю или группе пользователей | Правило применяется для всех объектов и указанного ограничения по пользователям. |
| Группа объектов не указана, выбран вариант **Без ограничений** | Правило применяется для всех объектов и всех пользователей. Может использоваться как общее правило. |

На один и тот же объект или ограничение по пользователям может подходить несколько правил. Если для объекта найдено несколько пулов соединений, использован будет пул с наивысшим приоритетом.

При сохранении правила выполняется проверка на дубликаты.

**Применение изменений и сброс кеша**

После изменения правил, групп объектов или пулов подключений необходимо сбросить кеш. Для этого используйте операции очистки кеша в соответствующих выборках настройки или стандартную операцию главного меню **Сервис > Управление решением > Очистить все кеши**.

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

~~~{note}
Условия применения правила по роли, профилю или группе пользователей не заменяют модель прав доступа Global ERP. Они определяют только то, для каких пользователей применяется правило применения пула.
~~~

**Алгоритм выбора пула**

При выполнении запроса система выбирает пул по объекту выполнения и условиям применения правила по пользователям.

Алгоритм выбора:

1. Система определяет объект выполнения запроса.
2. Система определяет пользователя, его роли, профиль или группу пользователей.
3. Система определяет, относится ли выполняемая операция к перечню операций и событий, для которых может использоваться пул реплики.
4. Система ищет правила, которые подходят для текущего объекта и пользователя. Правила без группы QoS учитываются как правила для всех объектов.
5. Если подходящие правила не найдены, система использует пул по умолчанию.
6. Если найдено несколько подходящих правил, система выбирает пул с наибольшим числовым значением приоритета.
7. Если выбранный пул является репликой, система использует его только для поддерживаемых операций и событий.
8. Система выполняет запрос через выбранный пул подключения.

### Приоритеты

В механизме используются 2 разных вида приоритета:

- **приоритет выбора пула**;
- **приоритет выполнения запросов в БД**.

Их нужно различать, потому что они применяются на разных уровнях.

**Приоритет выбора пула** задается в интерфейсе Global ERP на закладке **Пулы подключений**. Он используется, когда для одного объекта и условий по пользователям подходит несколько правил.

Чем больше числовое значение, тем выше приоритет пула. Например, пул с приоритетом `2` будет выбран раньше пула с приоритетом `1`.

Приоритет выбора пула определяет только порядок выбора между подходящими правилами. Ограничения по использованию master-БД и реплик описаны в разделе [Работа с master-БД и репликами](#работа-с-master-бд-и-репликами).

**Приоритет выполнения запросов в БД** задается на уровне СУБД, технического пользователя или механизма `pgpro_rp`. Этот приоритет определяет, в какой очередности или с каким весом БД обрабатывает запросы.

Приоритет выполнения запросов в БД применяется после выбора пула, когда запрос уже отправлен в БД через выбранное подключение.

~~~{attention}
Не смешивайте приоритет выбора пула и приоритет выполнения запроса в БД. Приоритет выбора пула влияет на выбор подключения в Global ERP. Приоритет выполнения запроса влияет на обработку запроса средствами СУБД.
~~~

## Работа с master-БД и репликами

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

Пулы с признаком **Реплика** используются только для:

- построения печатных форм;
- события выборки `beforeRefresh`;
- события выборки `onRefresh`;
- события выборки `onRefreshItem`;
- события выборки `onRefreshExt`;
- события выборки `afterRefresh`.

Другие запросы через пулы реплик не выполняются.

```{admonition} Особенности работы выборок с репликами

Для событий выборки `beforeRefresh` и `onRefresh` при использовании пула реплики применяются дополнительные правила. Они нужны из-за того, что реплика может содержать неактуальные данные.

При выполнении этих событий:

- если в сессии есть изменения, перед переключением пула они сбрасываются в БД с помощью `session.commit`;
- если выборка работает в режиме редактирования разделенного кеша `Shared cache`, на время использования пула реплики этот режим отключается, а кеш очищается; после выполнения события режим возвращается в исходное состояние;
- пул подключения устанавливается только для главной выборки на форме. Если правило настроено для выборки-детализации, пул реплики для нее использоваться не будет. Если эта же выборка открыта как главная на другой форме, правило может быть применено.
```

Пул, настроенный на master-БД, используется для остальных запросов настроенных объектов, включая операции изменения данных, выполнение действий, заполнение строк, фоновые задания и другие операции, не входящие в перечень событий для реплик.

Если для одного объекта настроен пул реплики и master-пул, система использует пул реплики только для перечисленных операций и событий. Остальные запросы выполняются через master-пул.

Для пулов реплик рекомендуется задавать более высокий приоритет, то есть большее числовое значение. Это позволяет при наличии нескольких подходящих правил использовать пул реплики для поддерживаемых операций и событий.

~~~{attention}
Пулы реплик используются только для построения печатных форм и событий выборки `beforeRefresh`, `onRefresh`, `onRefreshItem`, `onRefreshExt`, `afterRefresh`. Остальные запросы выполняются через master-БД.
~~~

## Технические сущности

В реализации используются следующие основные классы.

| Класс | Назначение |
|---|---|
| `ru.bitec.app.btk.database.pool.Btk_ConnectionPool` | Справочник пулов подключений к БД. |
| `ru.bitec.app.btk.qos.Btk_QosGroup` | Справочник групп QoS. |
| `ru.bitec.app.btk.qos.Btk_QosObjectGroup` | Коллекция объектов группы QoS. |
| `ru.bitec.app.btk.qos.Btk_QosRule` | Настройка правила QoS. |

### Справочник пулов подключений

Класс: `ru.bitec.app.btk.database.pool.Btk_ConnectionPool`.

| Атрибут | Описание |
|---|---|
| `sCode` | Код пула. |
| `sCaption` | Наименование пула. |
| `sDescription` | Описание пула. |
| `bReplica` | Признак реплики. |
| `nPriority` | Приоритет пула. |

В запросах справочника используется сортировка по приоритету.

### Группа QoS

Класс: `ru.bitec.app.btk.qos.Btk_QosGroup`.

| Атрибут | Описание |
|---|---|
| `sCode` | Код группы. |
| `sCaption` | Наименование группы. |
| `sDescription` | Описание группы. |

В запросах справочника используется сортировка по коду.

### Объекты группы QoS

Класс: `ru.bitec.app.btk.qos.Btk_QosObjectGroup`.

| Атрибут | Описание |
|---|---|
| `idQosGroup` | Группа QoS. |
| `gidObject` | Объект группы: печатная форма или фоновое задание. |
| `sSelection` | Системное имя выборки. |
| `sRepresentation` | Системное имя отображения. |

В запросах коллекции используется сортировка по дате создания. Дубликаты объектов внутри группы запрещены.

### Правило QoS

Класс: `ru.bitec.app.btk.qos.Btk_QosRule`.

| Атрибут | Описание |
|---|---|
| `gidTarget` | Ограничение по пользователю: роль, профиль или группа пользователей. |
| `idQosGroup` | Группа QoS. |
| `idConnectionPool` | Пул подключений. |