name: clickhouse service_id: 120 service_display_name: ClickHouse service_short_name: clickhouse service_man: '# Инструкция по управлению кластерами и пользователями ClickHouse

---

## Общая информация

ClickHouse — это колоночная система управления базами данных, предназначенная для обработки аналитических запросов в реальном времени. Платформа позволяет создавать, удалять, приостанавливать и возобновлять кластеры ClickHouse, а также управлять базами данных и пользователями.

Кластер создаётся через оператор Altinity (`https://github.com/Altinity/clickhouse-operator`) в ресурсной платформе типа `k8s`

Кластеры могут создаваться шардированными с произвольным количеством реплик. Для обеспечения отказоустойчивости и координации обязательно включение параметра `Создать ClickHouse-Keeper`.

Кластера создаются с обязательным бекапом. Для этого необходимо предварительно создать услугу `S3 Object Storage`.
---

## Доступные операции

* **create** — Создание кластера
* **delete** — Удаление кластера
* **suspend** — Приостановка работы кластера
* **resume** — Возобновление работы кластера
* **create_database** — Создание базы данных
* **delete_database** — Удаление базы данных
* **create_user** — Создание пользователя и настройка прав доступа к базе данных
* **delete_user** — Удаление пользователя

## Процесс создания и первого подключения

1. Выполнить операцию `create` - будет создан кластер
2. Выполнить операцию `create_database` - будет создана база данных
3. Выполнить операцию `create_user` - будет создан пользователь (выбрать доступ подключения к БД, созданной в п.2)

## Примеры подключения

### Подключение через HTTP-интерфейс

```bash
# Проверка доступности кластера
curl "http://<username>:<password>@<host>:8123/" -d "SELECT 1"

# Выполнение запроса
curl "http://<username>:<password>@<host>:8123/" -d "SHOW DATABASES"
```

## Простые кейсы
*Создать БД и обычной таблицы*
```clickhouse
CREATE TABLE database.table
(
id UInt64,
value String
)
ENGINE = MergeTree()
ORDER BY id;

INSERT INTO database.table SELECT number, toString(number) FROM numbers(10000000);

SELECT count() FROM database.table;
```
Базы и таблицы не реплицируются без специального ключа (`ON CLUSTER ''clickhousek8s''`)
В случае создания в стиле, описанным выше, необходимо будет выполнять действия на всех шардах/репликах


*Создание БД и шардированной таблицы*
```clickhouse
CREATE TABLE database.localUsers
(
id UInt64,
value String
)
ENGINE = MergeTree()
ORDER BY id;

CREATE TABLE database.shardedTable
AS localUsers
ENGINE = Distributed(''clickhousek8s'', ''database'', ''localUsers'', id);

INSERT INTO shardedTable SELECT number, toString(number) FROM numbers(10000000);

SELECT count() FROM shardedTable;
```
Важный момент - в данном примере таблицы придётся также выполнять на всех нодах ClickHouse

*Создание реплицируемой и шардированной таблицы*
```clickhouse
CREATE TABLE IF NOT EXISTS database.localUsers ON cluster ''clickhousek8s''
(
user_id UInt64,
name String,
email String
)
ENGINE = ReplicatedMergeTree(
''/clickhouse/tables/{shard}/localUsers'',
''{replica}''
)
ORDER BY user_id;

CREATE TABLE IF NOT EXISTS database.users ON cluster ''clickhousek8s''
AS database.localUsers
ENGINE = Distributed(''clickhousek8s'', ''database'', ''localUsers'', rand());

INSERT INTO database.users VALUES (1, ''Alice'', ''alice@example.com'');
INSERT INTO database.users VALUES (2, ''Bob'', ''bob@example.com'');
INSERT INTO database.users VALUES (3, ''Charlie'', ''charlie@example.com'');
INSERT INTO database.users VALUES (4, ''David'', ''david@example.com'');
INSERT INTO database.users VALUES (5, ''Gosha'', ''gosha@example.com'');
INSERT INTO database.users VALUES (6, ''Eve'', ''eve@example.com'');
INSERT INTO database.users VALUES (7, ''Frank'', ''frank@example.com'');
INSERT INTO database.users VALUES (8, ''Grace'', ''grace@example.com'');
INSERT INTO database.users VALUES (9, ''Hannah'', ''hannah@example.com'');
INSERT INTO database.users VALUES (10, ''Ivan'', ''ivan@example.com'');

SELECT * FROM database.localUsers;
SELECT * FROM database.users;

SELECT COUNT(*) AS total_users FROM database.users;
SELECT COUNT(*) AS total_users_local FROM database.localUsers;
```' lifecycle: suspend_on_destroy_default: true adopt_existing_on_create_default: false outputs: params: - code: state_params type: map - code: state_out type: map - code: state_params_flat type: map - code: state_out_flat type: map - code: vault_secrets type: map sensitive: true - code: vault_url type: string - code: vault_user_path type: string - code: vault_fields type: list operations: - name: create id: 181 kind: instance action: create man: Операция создания кластера ClickHouse

Для подключения к кластеру также необходимо создать базу данных через операцию `create_database` и создание пользователя через операцию `create_user` params: - id: 572 code: resourceRealm data_type: string required: true func: getAvailableResourceRealms descr: Кластер Kubernetes в котором будет развёрнуто приложение man: Выбрать платформу из списка

**Если список не отображается**
обратитесь к сервис менеджеру с вопросом предоставления ресурсной платформы sort: 10 - id: 573 code: s3Uid data_type: uuid required: true ref_svc_id: 12 descr: Экземпляр (учетная запись) S3 для резервного копирования. Резервное копирование обязательно man: '**Если список не отображается**
перейдите в раздел `S3 Object Storage`
операция `create`' sort: 20 - id: 574 code: resourceInstances data_type: integer > 0 required: true default: "1" maxvalue: 7 minvalue: 1 descr: 'Пример: `3`' man: '**Для синхронизации данных между репликами** необходимо включить `Создать ClickHouse-Keeper`' sort: 30 is_modifiable: true - id: 575 code: resourceInstancesShards data_type: integer > 0 required: true default: "1" maxvalue: 7 minvalue: 1 descr: 'Пример: `1`' man: '**Шард** - это часть данных, разделенная на разные узлы (серверы) для горизонтального масштабирования и обработки больших объемов информации.
**Реплика** - это точная копия данных внутри одного шарда' sort: 40 is_modifiable: true - id: 576 code: resourceCPU data_type: integer > 0 required: true default: "1000" maxvalue: 8000 minvalue: 1000 descr: 'Пример: `1000`' man: Указывается в Milicores
`1000` Mili == `1` Ядро sort: 50 is_modifiable: true - id: 577 code: resourceMemory data_type: integer > 0 required: true default: "1536" maxvalue: 8192 minvalue: 1536 descr: 'Пример: `2048`' man: Указывается в Megabytes sort: 60 is_modifiable: true - id: 578 code: appVersion data_type: string required: true default: "25.10" value_list: - "25.10" descr: Версия `clickhouse-server` sort: 70 is_modifiable: true - id: 579 code: resourceDisk data_type: integer > 0 required: true default: "10" maxvalue: 999 minvalue: 1 descr: 'Пример: `100`' man: Указывается в Gigabytes sort: 80 is_modifiable: true - id: 580 code: needExternalAddressMaster data_type: boolean required: true default: "false" value_list: - "false" - "true" descr: Позволяет подключиться извне к ClickHouse man: Для выделения IP также необходимо указать имя Ip-space.
Его можно получить из свойств ресурсной платформы sort: 90 is_modifiable: true - id: 581 code: ipSpaceNameMaster data_type: string required: false descr: 'Пример: `internet-no-antiddos-v1`' man: Имя ipSpace для публикации внешнего адреса

Не может быть пустым, если включен `Выделение белого ip для master ноды` sort: 100 is_modifiable: true - id: 582 code: needCreateKeeper data_type: boolean required: true default: "true" value_list: - "false" - "true" descr: Необходим для кластеризации ClickHouse man: Аналог `Zookeeper`, представленный от ClickHouse sort: 200 is_modifiable: true - id: 583 code: resourceCPUKeeper data_type: integer > 0 required: true default: "50" maxvalue: 8000 minvalue: 50 descr: 'Пример: `100`' man: Указывается в Milicores
`1000` Mili == `1` Ядро sort: 210 is_modifiable: true - id: 584 code: resourceMemoryKeeper data_type: integer > 0 required: true default: "152" maxvalue: 8192 minvalue: 152 descr: 'Пример: `256`' man: Указывается в Megabytes sort: 220 is_modifiable: true - id: 585 code: resourceInstancesKeeper data_type: integer > 0 required: true default: "1" value_list: - "1" - "3" maxvalue: 3 minvalue: 1 descr: 'Пример: `1`' man: Для **теста** - 1 нода.
Для **продуктива** - 3 ноды sort: 230 is_modifiable: true - id: 586 code: ext_BACKUP_SCHEDULE data_type: string required: true default: 0 0 * * * regex: ^((((\d+,)+\d+|(\d+(\/|-|#)\d+)|(\d+L?)|(\*(\/\d+)?)|(L(-\d+)?)|(\?)|([A-Z]{3}(-[A-Z]{3})?)) ?){5,7})|(@(annually|yearly|monthly|weekly|daily|hourly|reboot))|(@every (\d+(ns|us|µs|ms|s|m|h))+)$ descr: Принимает формат `CRON` sort: 500 is_modifiable: true - id: 587 code: ext_BACKUP_NUM_TO_RETAIN data_type: integer > 0 required: true default: "7" maxvalue: 60 minvalue: 3 descr: 'Пример: `7`' man: Кол-во **полных** резервных копий
Кол-во инкрементов - неограничено

Полная резервная копия выполняется раз в неделю
*Если изначально полной резервной копии нет* выполняется полный бекап
В остальные дни по крону выполняются **инкременты** sort: 510 is_modifiable: true - name: create_database id: 186 kind: subresource action: create subresource: database man: База данных создаётся на всех репликах кластера ClickHouse params: - id: 600 code: databaseName data_type: string required: true regex: ^[a-z0-9][a-z0-9.-]{1,61}[a-z0-9]$ descr: 'Пример: `db01`' sort: 10 - name: create_user id: 185 kind: subresource action: create subresource: user params: - id: 596 code: username data_type: string required: true regex: ^(?![0-9_])[a-zA-Z_][a-zA-Z0-9_]{0,62}$ maxlength: 62 minlength: 2 descr: 'Пример: `myusername`' sort: 10 - id: 598 code: databaseName data_type: json required: true default: '["database"]' descr: Необходимо указать массив существующих баз man: Если базы не существует - при выполнении операции вернётся ошибка sort: 30 - id: 599 code: accessHosts data_type: string required: true default: ::/0 descr: 'Пример: `::/0`' sort: 40 - name: delete id: 184 kind: instance action: delete man: Удаление возможно только после остановки сервиса через операцию `suspend`
После выполнения операции необходимо выждать определенное кол-во времени params: [] - name: delete_database id: 188 kind: subresource action: delete subresource: database man: Необратимое действие!!!
Трижды подумай, заблокируй телефон тимлида и не выполняй это действие params: - id: 602 code: databaseName data_type: string required: true descr: ВСЕ ДАННЫЕ ВНУТРИ БД БУДУТ УДАЛЕНЫ - name: delete_user id: 187 kind: subresource action: delete subresource: user params: - id: 601 code: username required: true descr: Имя пользователя, созданное через операцию `create_user` - name: modify id: 189 kind: instance action: modify params: - id: 603 code: resourceInstances data_type: integer > 0 required: true maxvalue: 7 minvalue: 1 descr: 'Пример: `3`' man: '**Для синхронизации данных между репликами** необходимо включить `Создать ClickHouse-Keeper`' sort: 10 - id: 604 code: resourceInstancesShards data_type: integer > 0 required: true maxvalue: 7 minvalue: 1 descr: 'Пример: `1`' man: '**Шард** - это часть данных, разделенная на разные узлы (серверы) для горизонтального масштабирования и обработки больших объемов информации.
**Реплика** - это точная копия данных внутри одного шарда' sort: 20 - id: 605 code: resourceCPU data_type: integer > 0 required: true maxvalue: 8000 minvalue: 1000 descr: 'Пример: `1000`' man: Указывается в Milicores
`1000` Mili == `1` Ядро sort: 30 - id: 606 code: resourceMemory data_type: integer > 0 required: true maxvalue: 8192 minvalue: 1536 descr: 'Пример: `2048`' man: Указывается в Megabytes sort: 40 - id: 607 code: appVersion data_type: string required: true default: "25.10" descr: Версия `clickhouse-server` sort: 50 - id: 608 code: resourceDisk data_type: integer > 0 required: true maxvalue: 999 minvalue: 1 descr: 'Пример: `100`' man: Указывается в Gigabytes
**Нельзя** выставлять меньше текущего значения sort: 60 - id: 609 code: needExternalAddressMaster data_type: boolean required: true value_list: - "false" - "true" descr: Позволяет подключиться извне к ClickHouse man: Для выделения IP также необходимо указать имя Ip-space.
Его можно получить из свойств ресурсной платформы sort: 70 - id: 610 code: ipSpaceNameMaster data_type: string required: true descr: 'Пример: `internet-no-antiddos-v1`' man: Имя ipSpace для публикации внешнего адреса

Не может быть пустым, если включен `Выделение белого ip для master ноды` sort: 80 - id: 611 code: needCreateKeeper data_type: boolean required: true value_list: - "false" - "true" descr: Необходим для кластеризации ClickHouse man: Аналог `Zookeeper`, представленный от ClickHouse sort: 200 - id: 612 code: resourceCPUKeeper data_type: integer > 0 required: true maxvalue: 8000 minvalue: 50 descr: 'Пример: `100`' man: Указывается в Milicores
`1000` Mili == `1` Ядро sort: 210 - id: 613 code: resourceMemoryKeeper data_type: integer > 0 required: true maxvalue: 8192 minvalue: 152 descr: 'Пример: `256`' man: Указывается в Megabytes sort: 220 - id: 614 code: resourceInstancesKeeper data_type: integer > 0 required: true value_list: - "1" - "3" maxvalue: 3 minvalue: 1 descr: 'Пример: `1`' man: Для **теста** - 1 нода.
Для **продуктива** - 3 ноды sort: 230 - id: 615 code: ext_BACKUP_SCHEDULE data_type: string required: true default: 0 0 * * * regex: ^((((\d+,)+\d+|(\d+(\/|-|#)\d+)|(\d+L?)|(\*(\/\d+)?)|(L(-\d+)?)|(\?)|([A-Z]{3}(-[A-Z]{3})?)) ?){5,7})|(@(annually|yearly|monthly|weekly|daily|hourly|reboot))|(@every (\d+(ns|us|µs|ms|s|m|h))+)$ descr: Принимает формат `CRON` sort: 500 - id: 616 code: ext_BACKUP_NUM_TO_RETAIN data_type: integer > 0 required: true maxvalue: 60 minvalue: 3 descr: 'Пример: `7`' man: Кол-во **полных** резервных копий
Кол-во инкрементов - неограничено

Полная резервная копия выполняется раз в неделю
*Если изначально полной резервной копии нет* выполняется полный бекап
В остальные дни по крону выполняются **инкременты** sort: 510 - name: resume id: 183 kind: instance action: resume params: [] - name: suspend id: 182 kind: instance action: suspend man: Операция приводит к удалению всех подов
Persistent Volume остаются нетронутыми params: []