# PostgreSQL

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

Как изменить параметры и применить изменения, описано в разделе [Параметры .env](https://webim.ru/kb/11.0/settings/env/).

## Подключение { #connection }

| Параметр | Тип | По умолчанию | Обязательный | Описание |
|---|---|---|---|---|
| `DATABASE_URL` | URL | Не задано | Да | Адрес подключения к основной базе данных в формате `postgresql://<пользователь>:<пароль>@<хост>:<порт>/<база>`. Можно указать несколько хостов через запятую: тогда **Webim** подключается к узлу, доступному для записи (`target_session_attrs=read-write`). Другой режим выбора узла задаётся параметром `?target_session_attrs=` в адресе.<br>Пример: `postgresql://webim:<пароль>@db.example.local:5432/webim`. |
| `DATABASE_SSL_MODE` | Строка | `prefer` | Нет | Режим TLS-подключения к PostgreSQL (параметр `sslmode` библиотеки libpq): `disable`, `allow`, `prefer`, `require`, `verify-ca` или `verify-full`. Для управляемых баз данных в облаке используйте `verify-full` вместе с `DATABASE_SSL_ROOT_CERT`. Действует и для реплики. |
| `DATABASE_SSL_ROOT_CERT` | Путь к файлу | Пусто | Нет | Путь к сертификату удостоверяющего центра (PEM) для проверки сертификата сервера PostgreSQL. |
| `DATABASE_CONNECT_TIMEOUT` | Целое число, секунды | `10` | Нет | Тайм-аут установки соединения с базой данных. |
| `DATABASE_STATEMENT_TIMEOUT` | Целое число, миллисекунды | `0` | Нет | Максимальная длительность одного запроса (`statement_timeout`). `0` — действует значение, заданное на сервере PostgreSQL. |
| `DATABASE_LOCK_TIMEOUT` | Целое число, миллисекунды | `0` | Нет | Максимальное время ожидания блокировки (`lock_timeout`). `0` — действует значение, заданное на сервере PostgreSQL. |
| `DATABASE_IDLE_IN_TRANSACTION_SESSION_TIMEOUT` | Целое число, миллисекунды | `0` | Нет | Время, через которое сервер закрывает сессию, простаивающую внутри транзакции (`idle_in_transaction_session_timeout`). `0` — действует значение, заданное на сервере PostgreSQL. |
| `DATABASE_DISABLE_PREPARED_STATEMENTS` | Логический | `False` | Нет | Отключает серверные курсоры. Включите, если **Webim** подключается к PostgreSQL через pgbouncer в режиме `transaction`: в этом режиме серверные курсоры не работают. Несмотря на имя, параметр не влияет на подготовленные запросы (prepared statements): **Webim** их не использует. |

## Пул соединений { #pool }

Пул соединений создаётся в каждом процессе **Webim**. Общее число соединений к базе данных — сумма по всем процессам: число процессов × `DB_POOL_SIZE`. Оно должно укладываться в лимит соединений PostgreSQL (`max_connections`) или пула pgbouncer.

| Параметр | Тип | По умолчанию | Обязательный | Описание |
|---|---|---|---|---|
| `USE_CONNECTION_POOLING` | Логический | `True` | Нет | Пул соединений внутри процесса. При включённом пуле параметры `DATABASE_CONN_MAX_AGE` и `DATABASE_CONN_HEALTH_CHECKS` не действуют. |
| `DB_POOL_MIN_SIZE` | Целое число | `4` | Нет | Минимальное число открытых соединений в пуле. |
| `DB_POOL_SIZE` | Целое число | `30` | Нет | Максимальное число соединений в пуле одного процесса. |
| `DB_POOL_TIMEOUT` | Дробное число, секунды | `30.0` | Нет | Максимальное время ожидания свободного соединения из пула. Если соединение не освободилось, запрос завершается ошибкой. |
| `DB_POOL_MAX_LIFETIME` | Дробное число, секунды | `600.0` | Нет | Максимальное время жизни соединения: по его истечении соединение закрывается и открывается заново. |
| `DB_POOL_MAX_IDLE` | Дробное число, секунды | `60.0` | Нет | Время простоя, после которого лишние соединения сверх `DB_POOL_MIN_SIZE` закрываются. |
| `DB_POOL_MAX_WAITING` | Целое число | `500` | Нет | Максимальное число запросов, ожидающих соединения из пула. Запросы сверх лимита сразу завершаются ошибкой. `0` — без ограничения. |
| `DB_POOL_NUM_WORKERS` | Целое число | `3` | Нет | Число фоновых потоков, которые открывают и проверяют соединения пула. |
| `DB_POOL_RECONNECT_TIMEOUT` | Целое число, секунды | Не задано | Нет | Присутствует в шаблоне файла `.env`, но в **Webim** 11.0 не действует. |
| `DATABASE_CONN_MAX_AGE` | Целое число, секунды | `0` | Нет | Время жизни постоянного соединения без пула. Действует, только если `USE_CONNECTION_POOLING=False`. `0` — соединение закрывается после каждого запроса. |
| `DATABASE_CONN_HEALTH_CHECKS` | Логический | `True` | Нет | Проверка постоянного соединения перед использованием. Действует, только если `USE_CONNECTION_POOLING=False`. |

## Реплика для чтения { #replica }

Реплика снимает с основной базы данных тяжёлые запросы на чтение: выгрузку данных статистики и BI-отчётов в ClickHouse, индексацию диалогов в поисковом движке и запросы Stored Data API. Какие функции читают данные с реплики, задают настройки Constance (см. [Использование read-реплики БД](https://webim.ru/kb/11.0/settings/constance/analytics.html#read-replica) и [Stored Data API](https://webim.ru/kb/11.0/settings/constance/workspace.html#stored-data-api)). Если реплика не задана, все запросы выполняются в основной базе данных.

| Параметр | Тип | По умолчанию | Обязательный | Описание |
|---|---|---|---|---|
| `DATABASE_REPLICA_URL` | URL | Не задано | Нет | Адрес подключения к реплике в том же формате, что и `DATABASE_URL`. Соединения с репликой открываются в режиме только для чтения. Если указано несколько хостов, по умолчанию выбирается резервный узел (`target_session_attrs=prefer-standby`). |
| `DATABASE_REPLICA_CONNECT_TIMEOUT` | Целое число, секунды | `10` | Нет | Тайм-аут установки соединения с репликой. |
| `DATABASE_REPLICA_STATEMENT_TIMEOUT` | Целое число, миллисекунды | `0` | Нет | Максимальная длительность запроса к реплике. `0` — действует значение, заданное на сервере. |
| `DATABASE_REPLICA_LOCK_TIMEOUT` | Целое число, миллисекунды | `0` | Нет | Максимальное время ожидания блокировки на реплике. `0` — действует значение, заданное на сервере. |
| `DATABASE_REPLICA_IDLE_IN_TRANSACTION_SESSION_TIMEOUT` | Целое число, миллисекунды | `0` | Нет | Время, через которое реплика закрывает сессию, простаивающую внутри транзакции. `0` — действует значение, заданное на сервере. |
| `DB_REPLICA_POOL_MIN_SIZE` | Целое число | `1` | Нет | Минимальное число открытых соединений в пуле реплики. |
| `DB_REPLICA_POOL_SIZE` | Целое число | `5` | Нет | Максимальное число соединений в пуле реплики одного процесса. |
| `DB_REPLICA_POOL_TIMEOUT` | Дробное число, секунды | `30.0` | Нет | Максимальное время ожидания свободного соединения из пула реплики. |
| `DB_REPLICA_POOL_MAX_LIFETIME` | Дробное число, секунды | `600.0` | Нет | Максимальное время жизни соединения с репликой. |
| `DB_REPLICA_POOL_MAX_IDLE` | Дробное число, секунды | `60.0` | Нет | Время простоя, после которого лишние соединения с репликой закрываются. |
| `DB_REPLICA_POOL_NUM_WORKERS` | Целое число | `1` | Нет | Число фоновых потоков пула реплики. |

---

Источник: https://webim.ru/kb/11.0/settings/env/postgresql.html
