# Конфигурация СУБД Все необходимые данные для подключения и работы сервера приложения с используемыми СУБД можно задать в файле `/etc/webim/db.json`, а также в json-файлах в директории `/etc/webim/db.json.d`. При инициализации сервера все данные, хранящиеся в этих файлах, будут объединены в один словарь, так что Вы можете использовать оба предложенных способа. После создания словаря в нём будет произведён поиск необходимых данных. При удачном исходе поиска данные будут использованы для подключения к СУБД. Вы можете задать конфигурации для всех используемых системой СУБД: * Реляционные СУБД - **MySQL**, **MariaDB**, **PostgreSQL**. Ключевые СУБД, используются для хранения большей части данных; * Колоночная СУБД - **ClickHouse**, используется для работы с модулем **Статистики**; * Поисковый движок — **Elasticsearch** или **OpenSearch** (на **Webim Server 10.8+** подключение к обоим вариантам поддерживается одинаково), используется для ускорения поиска по истории чатов; Из представленного списка обязательными для работы сервиса являются только реляционные СУБД - одна из них должна быть активна, настроена и подключена к серверу. Остальные СУБД являются опциональными и подключаются при необходимости. ## Структура файла конфигурации СУБД В `db.json` предусмотрена конкретная структура, неследование которой может повлечь за собой неработоспособность сервиса. Параметры для подключения СУБД хранятся в объекте `dbs`. Необходимым минимумом для работы сервиса является наличие в объекте `dbs` объектов `meta` и `pro.default`, внутри которых хранятся параметры, используемые сервером для подключения к соответствующим базам реляционной СУБД. Перечень принимаемых параметров зависит от типа СУБД, который указывается в соответствующем объекте. В объекте `default` содержатся параметры для подключения к СУБД по умолчанию. Его наличие является обязательным для схемы `pro` и опциональным для остальных СУБД (кроме схемы `meta` - её параметры не оборачиваются в какие-либо дополнительные объекты, т. к. эта схема существует в единственном экземпляре и содержит в себе информацию об аккаунтах). В случае, если на Вашем **Webim Server** работает только один аккаунт, Вы можете использовать в качестве ключа обёртки как `default`, так и имя Вашего аккаунта (указанный Вами при регистрации сайт без точек). В тех случаях, если на Вашем **Webim Server** работают несколько аккаунтов, необходимо "расселить" их по разным БД, в противном случае данные из БД будут доступны всем аккаунтам. Для каждого аккаунта необходимо указать свою конфигурацию для подключения к СУБД, ключом для такой конфигурации будет имя аккаунта (например, `wwwtestru`). При необходимости (например, при возникновении дублирования данных или большом размере конфигурационного файла) параметры подключения к СУБД можно хранить отдельно от основной конфигурации (в т. ч. и в другом файле). Для этого используется объект `connections`, внутри которого могут находиться объекты с произвольными именами, содержащие в себе параметры подключения к СУБД. Для их применения в конфигурации необходимо указать параметр `connection`, значением которого является один из ключей `connections`. Для **ClickHouse**-кластера в **`dbs.stats.default`** используется параметр `cluster_connection`. Он указывает на ключ в `connections` и ожидает объект с типом подключения `clickhouse_cluster`. !!! Note "N.B." Подключение к **ClickHouse** в режиме кластера (`cluster_connection` / `clickhouse_cluster`) поддерживается **начиная с версии Webim [10.8](https://webim.ru/webim-10-8/)**. Во избежание путаницы мы рекомендуем удалять из конфигурации подключения параметры, указанные в используемом объекте из `connections`. Параметры из `connection`/`cluster_connection` являются приоритетными в сравнении с остальными параметрами конфигурации, указанными в объекте. ## Описание принимаемых параметров конфигурации СУБД Список возможных типов СУБД: * `mysql` * `postgresql` * `clickhouse` * `elastic` (в т. ч. типы `elasticsearch` и `opensearch` в значении поля `type` внутри секции — см. таблицу ниже) * `clickhouse_cluster` — только в объекте `connections`: описание кластера **ClickHouse** для ссылки через `cluster_connection` (**Webim** [10.8](https://webim.ru/webim-10-8/) и выше) !!! Note "N.B." В случае, если Вы желаете использовать **MariaDB**, в качестве типа СУБД укажите `mysql`. Принимаемые параметры этой СУБД аналогичны параметрам **MySQL**. Список принимаемых параметров для **MySQL** и **MariaDB**: | Параметр | Тип | Пример | Описание | Является обязательным | | ---------- | --------- | ------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------- | | `type` | `String` | `mysql` | Тип СУБД | Нет, так как любая СУБД по умолчанию имеет тип `mysql` | | `host` | `String` | `127.0.0.1` | Адрес сервера СУБД (IPv4 или доменное имя) | Да | | `port` | `Integer` | `3306` | Порт для подключения к СУБД | Нет, по умолчанию используется порт, соответствующий типу СУБД (параметр `type`) | | `user` | `String` | `webim_site` | Учётная запись СУБД, используемая для выполнения запросов к БД. Обязательно наличие **всех** привилегий | Да | | `password` | `String` | `somepass` | Пароль для соответствующей учётной записи СУБД | Да | | `database` | `String` | `webim_hosted_meta` | Название БД, к которой будет осуществляться подключение | Да | | `slave` | `Object` | | [Slave-узел](https://ru.wikipedia.org/wiki/%D0%92%D0%B5%D0%B4%D1%83%D1%89%D0%B8%D0%B9_%E2%80%94_%D0%B2%D0%B5%D0%B4%D0%BE%D0%BC%D1%8B%D0%B9) для СУБД, используется при масштабировании (репликации). Внутри объекта содержатся аналогичные приведённым в таблице параметры. Репликация между различными СУБД **не поддерживается**. | Нет | Список принимаемых параметров для **PostgreSQL**: | Параметр | Тип | Пример | Описание | Является обязательным | | ---------- | --------- | ------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------- | | `type` | `String` | `postgresql` | Тип СУБД | Да | | `host` | `String` | `127.0.0.1` | Адрес сервера СУБД (IPv4 или доменное имя) | Да | | `port` | `Integer` | `5432` | Порт для подключения к СУБД | Нет, по умолчанию используется порт, соответствующий типу СУБД (параметр `type`) | | `user` | `String` | `webim_site` | Учётная запись СУБД, используемая для выполнения запросов к БД. Обязательно наличие **всех** привилегий | Да | | `password` | `String` | `somepass` | Пароль для соответствующей учётной записи СУБД | Да | | `db` | `String` | `some_db` | Название БД, к которой будет осуществляться подключение | Да | | `schema` | `String` | `webim_hosted_meta` | Название схемы, с которой будут выполняться действия | Да | | `slave` | `Object` | | [Slave-узел](https://ru.wikipedia.org/wiki/%D0%92%D0%B5%D0%B4%D1%83%D1%89%D0%B8%D0%B9_%E2%80%94_%D0%B2%D0%B5%D0%B4%D0%BE%D0%BC%D1%8B%D0%B9) для СУБД, используется при масштабировании (репликации). Внутри объекта содержатся аналогичные приведённым в таблице параметры. Репликация между различными СУБД **не поддерживается**. | Нет | Список принимаемых параметров для **ClickHouse**: | Параметр | Тип | Пример | Описание | Является обязательным | | ---------- | --------- | ------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------- | | `type` | `String` | `clickhouse` | Тип СУБД | Да | | `host` | `String` | `127.0.0.1` | Адрес сервера СУБД (IPv4 или доменное имя) | Да | | `port` | `Integer` | `9000` | Порт для подключения к СУБД | Нет; для **ClickHouse** по умолчанию используется порт **9000** (нативный протокол), если порт не задан явно | | `user` | `String` | `webim_stats` | Учётная запись СУБД, используемая для выполнения запросов к БД. Обязательно наличие **всех** привилегий | Да | | `password` | `String` | `somepass` | Пароль для соответствующей учётной записи СУБД | Да | | `database` | `String` | `webim_stats` | Название БД, к которой будет осуществляться подключение | Да | | `slave` | `Object` | | [Slave-узел](https://ru.wikipedia.org/wiki/%D0%92%D0%B5%D0%B4%D1%83%D1%89%D0%B8%D0%B9_%E2%80%94_%D0%B2%D0%B5%D0%B4%D0%BE%D0%BC%D1%8B%D0%B9) для СУБД, используется при масштабировании (репликации). Внутри объекта содержатся аналогичные приведённым в таблице параметры. | Нет | Объект **`stats`** в `dbs` обязателен. Для одного узла **ClickHouse** без кластера его часто оставляют пустым (`"stats": {}`), а параметры подключения задают в **`stats_root`** (см. примеры ниже в статье). Для **кластера** (**Webim** [10.8](https://webim.ru/webim-10-8/) и выше) используйте **`stats.default`**: в нём указывают `cluster_connection` и связанные поля (таблицы ниже и пример). Список полей объекта с `type: clickhouse_cluster` в `connections` (кластер **ClickHouse**; **Webim** [10.8](https://webim.ru/webim-10-8/) и выше): | Параметр | Тип | Пример | Описание | Является обязательным | | -------------- | --------- | -------------------- | ------------------------------------------------------------------------------------------------ | --------------------- | | `type` | `String` | `clickhouse_cluster` | Тип подключения в `connections` | Да | | `cluster_name` | `String` | `webim_stats_cluster` | Имя кластера в **ClickHouse** (Distributed-таблицы, миграции) | Да | | `nodes` | `Array` | | Список узлов кластера; каждый элемент — объект с `type: clickhouse` (см. следующую таблицу) | Да | Список полей **одного узла** в массиве `nodes` (объект с `type: clickhouse`): | Параметр | Тип | Пример | Описание | Является обязательным | | ---------- | --------- | ------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------- | | `type` | `String` | `clickhouse` | Тип узла | Да | | `host` | `String` | `clickhouse-01.local` | Адрес узла (IPv4 или доменное имя) | Да | | `port` | `Integer` | `9000` | Порт для подключения к узлу | Нет, по умолчанию используется порт **9000** | | `user` | `String` | `webim_stats` | Учётная запись **ClickHouse** на этом узле для рабочих запросов статистики | Да | | `password` | `String` | `` | Пароль учётной записи из поля `user` | Да | | `database` | `String` | `webim_stats` | Имя БД на узле. Должно быть задано **либо** в каждом элементе `nodes`, **либо** один раз в том же `default`, где указан `cluster_connection` (в `dbs.stats.default` или в account config): при развёртывании кластера поля из этого объекта дополняют каждый узел | Да (одним из этих способов) | | `root_user` | `String` | `default` | Учётная запись **ClickHouse** с правами, достаточными для служебных операций (создание БД, миграции). Задаётся в каждом узле **или** один раз в том же `default`, где указан `cluster_connection` | Да (одним из этих способов) | | `root_password` | `String` | `` | Пароль для `root_user` | Да (одним из этих способов) | | `weight` | `Integer` | `2` | Вес узла при выборе узла для записи. Задействуется только если **`weight` задан у всех узлов** и ни у одного не равен нулю; иначе **Webim Server** выбирает узел **случайно, с равной вероятностью** среди узлов списка | Нет | Для настройки **ClickHouse**-кластера в **`dbs.stats.default`** укажите `cluster_connection`, а в `connections` создайте объект типа `clickhouse_cluster` с `cluster_name` и массивом `nodes`. Ниже имя БД и учётные данные «root» заданы один раз в `stats.default` и не дублируются в `nodes`: !!! Note "N.B." В инструкции по обновлению до **Webim Server** 10.8 (файл **UPGRADE.md** в поставке сервера) кластерное подключение добавляют именно в **`stats.default`**, при этом **старый** `connection` в **`stats_root.default`** для прежнего одиночного узла **удалять не обязательно** — оба варианта могут временно сосуществовать. ``` { "dbs": { "stats": { "default": { "cluster_connection": "cluster_stats", "database": "webim_stats", "root_user": "default", "root_password": "" } } }, "connections": { "cluster_stats": { "type": "clickhouse_cluster", "cluster_name": "webim_stats_cluster", "nodes": [ { "type": "clickhouse", "host": "clickhouse-01.local", "port": 9000, "user": "webim_stats", "password": "", "weight": 2 }, { "type": "clickhouse", "host": "clickhouse-02.local", "port": 9000, "user": "webim_stats", "password": "", "weight": 1 } ] } } } ``` Список принимаемых параметров для **Elasticsearch** и **OpenSearch** (начиная с **Webim Server 10.8** в поле `type` допускаются значения `elastic`, `elasticsearch` и `opensearch`; секцию в `dbs` можно именовать `elastic` или `history`): | Параметр | Тип | Пример | Описание | Является обязательным | | --------------------- | --------- | --------------------- | ------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------- | | `type` | `String` | `elastic` | Тип СУБД: `elastic`, `elasticsearch` или `opensearch` | Да | | `host` | `String` | `127.0.0.1` | Адрес сервера СУБД (IPv4 или доменное имя) | Да | | `port` | `Integer` | `9200` | Порт для подключения к СУБД | Нет, по умолчанию используется порт, соответствующий типу СУБД (параметр `type`) | | `user` | `String` | `elastic` | Учётная запись СУБД, используемая для выполнения запросов к БД. Обязательно наличие **всех** привилегий | Да | | `password` | `String` | `somepass` | Пароль для соответствующей учётной записи СУБД | Да | | `scheme` | `String` | `http` | Используемый протокол | Да | | `index_name_template` | `String` | `{account}--{object}` | Шаблон, по которому будут формироваться индексы | Да | ## Примеры конфигураций ### Стандартная конфигурация: реляционная СУБД (MySQL) ``` { "dbs": { "meta": { "type": "mysql", "host": "database", "user": "webim_site", "password": "password", "database": "webim_site" }, "pro": { "default": { "connection": "db1" } } }, "connections": { "db1": { "type": "mysql", "host": "database", "user": "webim_service", "password": "password" } } } ``` ### Рекомендуемая конфигурация: реляционная СУБД (MySQL), колоночная СУБД (ClickHouse) ``` { "dbs": { "meta": { "type": "mysql", "host": "database", "user": "webim_site", "password": "password", "database": "webim_site" }, "pro": { "default": { "connection": "db1" } }, "stats_root": { "default": { "connection": "ch1" } }, "stats": {} }, "connections": { "db1": { "type": "mysql", "host": "database", "user": "webim_service", "password": "password" }, "ch1": { "type": "clickhouse", "host": "clickhouse", "user": "default", "password": "password" } } } ``` ### Кластер ClickHouse (Webim 10.8 и выше) ``` { "dbs": { "meta": { "type": "mysql", "host": "database", "user": "webim_site", "password": "password", "database": "webim_site" }, "pro": { "default": { "connection": "db1" } }, "stats": { "default": { "cluster_connection": "cluster_stats", "database": "webim_stats", "root_user": "default", "root_password": "" } } }, "connections": { "db1": { "type": "mysql", "host": "database", "user": "webim_service", "password": "password" }, "cluster_stats": { "type": "clickhouse_cluster", "cluster_name": "webim_stats_cluster", "nodes": [ { "type": "clickhouse", "host": "clickhouse-01.local", "port": 9000, "user": "webim_stats", "password": "", "weight": 2 }, { "type": "clickhouse", "host": "clickhouse-02.local", "port": 9000, "user": "webim_stats", "password": "", "weight": 1 } ] } } } ``` ### Продвинутая конфигурация: реляционная СУБД (MySQL) с репликацией, колоночная СУБД (ClickHouse), поисковый движок (Elasticsearch или OpenSearch) ``` { "dbs": { "meta": { "type": "mysql", "host": "database", "user": "webim_site", "password": "password", "database": "webim_site" }, "pro": { "default": { "connection": "db1", "slave": { "connection": "db2" } } }, "stats_root": { "default": { "connection": "ch1" } }, "stats": {}, "elastic": { "default": { "type": "elastic", "host": "elasticsearch", "port": 9200, "user": "elastic", "password": "password", "scheme": "http", "index_name_template": "{account}-{object}" } } }, "connections": { "db1": { "type": "mysql", "host": "database", "user": "webim_service", "password": "password" }, "db2": { "type": "mysql", "host": "database_replica", "user": "webim_service", "password": "webim_service" }, "ch1": { "type": "clickhouse", "host": "clickhouse", "user": "default", "password": "password" } } } ``` --- Источник: https://webim.ru/kb/devops/db-configuration.html