# Менеджмент СУБД через wmdb
`wmdb` — компонент **Webim Server**, предназначенный для менеджмента БД и схем (далее используется термин «БД», включая схемы при использовании **PostgreSQL** в качестве табличной СУБД).
`wmdb` позволяет выполнять операции с БД без запуска основного кода Webim Server. Это полезно для отдельных сценариев, например, для инициализации БД на hosted-размещениях.
`wmdb` предоставляет CLI-интерфейс для базовых операций с хранилищами Webim. Запуск выполняется из виртуального окружения. `sudo` не требуется.
`wmdb` используется для управления хранилищами Webim:
* `meta` (реляционная СУБД) — системные данные и аккаунты.
* `pro` (реляционная СУБД) — данные конкретного аккаунта.
* `stats` (ClickHouse) — аналитические данные конкретного аккаунта.
Также `wmdb` содержит команды для обновления конфигурации тарифов в `meta`.
## Установка и запуск
`wmdb` запускается без `sudo`.
Для работы команд должны быть доступны конфигурационные файлы Webim Server (например, каталог `/etc/webim`), включая настройки подключений к СУБД.
### Запуск команд
В зависимости от окружения используйте один из вариантов.
* Если в окружении доступна консольная команда:
```
wmdb --help
wmdb --version
```
* Если консольной команды нет, запускайте как Python-модуль:
```
python3 -m wmdb --help
python3 -m wmdb --version
```
!!! Note "N.B."
Далее в статье команды показаны в виде `wmdb ...`. Для запуска через модуль заменяйте `wmdb` на `python3 -m wmdb`.
## Синтаксис
```
wmdb [object [ACCOUNT_NAME] command [args]] [--help]
wmdb --version
```
## Объекты и флаги
В `wmdb` есть 4 объекта:
* Схема `meta` в реляционной СУБД — [`meta`](#meta)
* Схема `pro` в реляционной СУБД — [`pro`](#pro)
* Схема `stats` в колоночной СУБД — [`stats`](#stats)
* Аккаунт **Webim** (записи в `meta` + схема `pro`) — [`account`](#account)
Специальные флаги:
* `--version` — вывести версию `wmdb`.
* `--help` — вывести подсказку по командам.
!!! Note "N.B."
Для выполнения команд в конфигурации СУБД **Webim Server** должны быть указаны учётные записи СУБД с привилегиями, достаточными для создания и изменения БД/схем и таблиц.
## Команды CLI
### `wmdb meta` { #meta }
Команды для `meta` (имя схемы/БД определяется конфигурационным файлом Webim Server).
Доступные команды:
* `wmdb meta create` — создать `meta` и записать минимальные данные.
До выполнения команды `meta` существовать **не должно**.
* `wmdb meta exists` — проверить существование `meta`.
Коды возврата:
* `0` — `meta` существует.
* `1` — `meta` не найдена.
* `wmdb meta upgrade` — обновить схему `meta` до актуальной версии (миграции).
Возможные ошибки:
* `Meta schema '...' already exists` — `meta` уже существует.
---
### `wmdb pro` { #pro }
Команды для `pro` аккаунта `ACCOUNT_NAME` (имя схемы/БД определяется конфигурационным файлом Webim Server).
Доступные команды:
* `wmdb pro ACCOUNT_NAME create` — создать `pro` для аккаунта `ACCOUNT_NAME`.
Требования:
* настройки соединения и конфигурация `pro` должны быть заданы в `db.json`;
* до выполнения команды `pro` для аккаунта существовать **не должно**.
* `wmdb pro ACCOUNT_NAME exists` — проверить существование `pro` для аккаунта.
Коды возврата:
* `0` — `pro` существует.
* `1` — `pro` не найдена.
* `wmdb pro ACCOUNT_NAME current` — показать текущую версию схемы `pro`.
* `wmdb pro ACCOUNT_NAME tree` — показать дерево ревизий схемы `pro`.
* `wmdb pro ACCOUNT_NAME upgrade [REVISION]` — обновить схему `pro` до версии `REVISION`.
Если `REVISION` не указана, используется `head`.
* `wmdb pro ACCOUNT_NAME downgrade REVISION` — даунгрейд схемы `pro` до версии `REVISION`.
* `wmdb pro ACCOUNT_NAME drop --yes --yes --yes` — удалить `pro` аккаунта.
Возможные ошибки:
* `Pro schema '...' already exists` — `pro` для аккаунта уже существует.
!!! Note "N.B."
При даунгрейде `pro` рекомендуется сначала выполнить [даунгрейд `stats`](#stats-migrate-down).
---
### `wmdb stats` { #stats }
Команды для `stats` аккаунта `ACCOUNT_NAME` (ClickHouse).
Доступные команды:
* `wmdb stats ACCOUNT_NAME create` — создать `stats` для аккаунта `ACCOUNT_NAME`.
* `wmdb stats ACCOUNT_NAME drop --yes --yes --yes` — удалить `stats` аккаунта.
* `wmdb stats ACCOUNT_NAME current` — показать текущую версию `stats`.
* `wmdb stats ACCOUNT_NAME tree` — показать дерево ревизий `stats`.
* `wmdb stats ACCOUNT_NAME upgrade [REVISION]` — обновить `stats` до версии `REVISION`.
Если `REVISION` не указана, используется `head`.
* `wmdb stats ACCOUNT_NAME downgrade REVISION` — даунгрейд `stats` до версии `REVISION`.
Возможные ошибки:
* `stats ACCOUNT_NAME [upgrade | downgrade] REVISION: Failed to load categories` — ошибка при загрузке категорий.
!!! Note "N.B."
При апгрейде `stats` рекомендуется сначала выполнить [апгрейд `pro`](#pro-migrate-up).
---
### `wmdb account` { #account }
Команды для аккаунтов **Webim**.
Аккаунт считается существующим, если в `meta` есть запись об аккаунте (таблица `account_t`).
Доступные команды:
* `wmdb account ACCOUNT_NAME create` — создать новый аккаунт `ACCOUNT_NAME` и инициализировать его хранилища.
Требования:
* `meta` должна существовать;
* аккаунта `ACCOUNT_NAME` не должно быть в `meta`;
* `pro` для аккаунта `ACCOUNT_NAME` существовать **не должна**.
* `wmdb account ACCOUNT_NAME exists` — проверить существование аккаунта.
Коды возврата:
* `0` — аккаунт существует.
* `1` — аккаунт не найден.
---
#### `create` — создание аккаунта { #account-create }
**Синтаксис**
```
wmdb account ACCOUNT_NAME create [ПАРАМЕТРЫ]
```
**Аргументы**
| Параметр | Пример | Описание | Обязательный параметр |
|-------------------------|--------------------------------------------------------------------|-----------------------------------------------------------------------------------------------------------|-----------------------|
| `--agent-email` | `somemail@mail.com` | Адрес электронной почты оператора. | Да |
| `--agent-name` | `Agent` | Имя оператора. | Да |
| `--agent-password` | `StrongPassword123` | Пароль оператора. Если не указан и не указан `--agent-password-hash`, пароль будет запрошен интерактивно. | Нет |
| `--agent-password-hash` | `a6c79a27049109e472b246b5dfbe08aedff1e9e2259597e54032dbad4958d4ad` | Хэш пароля оператора. Альтернатива `--agent-password`. | Нет |
| `--partner-name` | `webim` | Имя партнёра. По умолчанию `webim`. | Нет |
| `--phone` | `79001234567` | Номер телефона организации. | Да |
| `--site` | `somesite.com` | Сайт организации. | Да |
| `--timezone` | `Europe/Moscow` | Часовой пояс аккаунта. | Да |
| `--language` | `ru` | Ключ языка аккаунта. | Да |
| `--trial-period-days` | `7` | Длительность демо-периода в днях. Значение не менее `1`, по умолчанию `7`. | Нет |
Пример (пароль строкой):
```
wmdb account testcom create --agent-email=[somemail@mail.com](mailto:somemail@mail.com) --agent-name=Agent
--agent-password=StrongPassword123 --partner-name=webim --phone=79001234567
--site=somesite.com --timezone=Europe/Moscow --language=ru --trial-period-days=7
```
Пример (пароль хэшем):
```
wmdb account testcom create --agent-email=[somemail@mail.com](mailto:somemail@mail.com) --agent-name=Agent
--agent-password-hash=a6c79a27049109e472b246b5dfbe08aedff1e9e2259597e54032dbad4958d4ad
--partner-name=webim --phone=79001234567 --site=somesite.com --timezone=Europe/Moscow
--language=ru --trial-period-days=7
```
Возможные ошибки:
* `Account '...' already exists` — аккаунт уже существует.
---
#### `exists` — проверка существования { #account-exists }
**Синтаксис**
```
wmdb account ACCOUNT_NAME exists
```
**Коды возврата**
* `0` — аккаунт с именем `ACCOUNT_NAME` существует.
* `1` — аккаунт не найден.
---
### `wmdb tariffs`
Команды для конфигурации тарифов в `meta`.
Доступные команды:
* `wmdb tariffs diff` — показать отличия конфигурации тарифов из конфигурационных файлов Webim Server от данных в `meta`.
* `wmdb tariffs update` — обновить конфигурацию тарифов в `meta` по данным из конфигурационных файлов Webim Server.
---
Источник: https://webim.ru/kb/devops/wmdb.html