Что получится
ClickHouse 26.8 в той же VPC, что и Kafka; интеграция orders_kafka; таблица shop.orders, в которую события из топика orders попадают сами; агрегаты по выручке, которые обновляются в реальном времени.
Что понадобится
- Кластер Kafka с топиком
ordersи сервер в той же сети — например, из сценария «События между микросервисами» в разделе Kafka. Можно начать и с пустого проекта: шаги ниже создают всё нужное. - CLI
h3с API-ключом проекта (h3 init): пользователи и интеграции ClickHouse настраиваются через API. - Сервер в сети проекта для SQL-клиента: ClickHouse без публичного IP доступен только из VPC.
-
Шаг 1. Подготовьте Kafka: топик и пользователя для ClickHouse
Если кластера ещё нет: Базы данных → Создать базу данных → СУБД Kafka, Брокеры «1 брокер», vCPU 1, RAM 2 ГБ, Диски 10 ГБ, Имя базы данных
events→ Создать базу данных.ClickHouse будет читать топик от своего пользователя с правом только на чтение, поэтому его права не пересекаются с правами сервисов.
Консоль
- В карточке кластера Kafka в разделе «Топики» нажмите Создать топик: Имя топика
orders, Партиции3→ Создать (если топика ещё нет). - В разделе «Пользователи» нажмите Создать пользователя: Имя пользователя
clickhouse, Доступ — «Только чтение», Топикиorders→ Создать. - Запишите Логин из окна «Пользователь создан», например
clickhouse-1a2b3c4d. Пароль ClickHouse возьмёт сам — копировать его не нужно.
CLI
Терминалh3 db topic create <id Kafka> --name orders --partitions 3 echo '{"name":"clickhouse","grants":[{"database":"orders","preset":"readonly"}]}' | h3 db user create <id Kafka> --from-file - h3 db user list <id Kafka> # логин с суффиксом — в колонке имениПроверка
В таблице «Пользователи» есть логин
clickhouse-…с доступом «Только чтение» наorders. - В карточке кластера Kafka в разделе «Топики» нажмите Создать топик: Имя топика
-
Шаг 2. Создайте ClickHouse в той же сети
Интеграция работает только между базами одного проекта и одной VPC. Публичный IP не нужен: ClickHouse читает Kafka по внутренним адресам, а SQL-клиент работает с сервера в сети проекта.
Консоль
- Базы данных → Создать. СУБД — ClickHouse 26.8. vCPU — 2, RAM — 4 ГБ (минимум для ClickHouse), Диски — 20 ГБ.
- Имя базы данных —
analytics. Сеть — та же, что у Kafka. Публичный IP оставьте выключенным. - Нажмите Создать базу данных.
CLI
Терминалh3 db create --name analytics --engine clickhouse --version 26.8 --cpu 2 --memory 4Gi --size 20 h3 db get <id ClickHouse> -o json # internalIP — адрес в VPCПроверка
Статус — «Работает». В блоке «Подключение» на вкладке «Внутри VPC» — Адрес в VPC: запишите его.
-
Шаг 3. Заведите пользователя и базу для потока
Права в ClickHouse выдаются пресетом на базу:
readonly,readwriteилиadmin. Пользовательetlбудет владельцем базыshop(пресетadmin: таблицы, представления, словари) и получит доступ к интеграции. Встроенному пользователюappинтеграции не выдаются.CLI
Терминалh3 db user create <id ClickHouse> --name etl # сохраните пароль из ответа h3 db database create <id ClickHouse> --name shop --owner etl h3 db user list <id ClickHouse>Проверка
У пользователя
etlв доступе —shopс пресетомadmin, статус «READY». Пароль можно посмотреть снова:h3 db user credentials <id ClickHouse> etl.Если не получилось
INVALID_NAME— имена пользователей и баз ClickHouse: латинские строчные буквы, цифры и_, начинаются с буквы или_. Дефис недопустим.
-
Шаг 4. Создайте интеграцию с Kafka
Интеграция — именованная коллекция ClickHouse с адресами брокеров, логином, паролем и сертификатом CA кластера Kafka. Платформа берёт пароль из своих записей, в запросах и ответах его нет, а пользователи из
grantToмогут коллекцией пользоваться, но не могут её прочитать или подменить адрес.CLI
Терминалh3 api POST /api/databases/v1/<id ClickHouse>/integrations -d '{ "name": "orders_kafka", "kind": "kafka", "sourceDatabaseId": "<id Kafka>", "user": "<логин clickhouse-…>", "grantTo": ["etl"] }' h3 api GET /api/databases/v1/<id ClickHouse>/integrationsПроверка
Интеграция
orders_kafkaв статусеREADY.Если не получилось
409 SOURCE_NOT_REACHABLE— Kafka в другой сети: интеграция работает только в пределах одной VPC проекта.UNKNOWN_USER— пользователя нет в/usersClickHouse. Встроенныйappсюда не подходит, нужен созданный пользователь.- Ошибка авторизации Kafka при чтении — в
userуказано имя без суффикса. Нужен логин целиком.
-
Шаг 5. Подключитесь к ClickHouse с сервера
Подключение — только по TLS: нативный протокол на порту
9440, HTTPS —8443. Сертификат сервера подписан CA платформы «h3llo Managed Databases CA» и содержит имяdb.h3llo.cloud. Поэтому сопоставим это имя с адресом базы в/etc/hostsи включим строгую проверку.Скачайте в карточке ClickHouse Скачать сертификат CA (файл
h3llo-db-ca.pem) и скопируйте его на сервер.На сервереecho "<адрес в VPC> db.h3llo.cloud" | sudo tee -a /etc/hosts curl https://clickhouse.com/ | sh # скачает один файл ./clickhouse cat > ch.xml <<'EOF' <config> <openSSL><client> <loadDefaultCAFile>false</loadDefaultCAFile> <caConfig>/home/user/h3llo-db-ca.pem</caConfig> <verificationMode>strict</verificationMode> <invalidCertificateHandler><name>RejectCertificateHandler</name></invalidCertificateHandler> </client></openSSL> </config> EOF ./clickhouse client --config-file ch.xml --secure --host db.h3llo.cloud --port 9440 \ --user etl --password '<пароль etl>' --database shop --query 'SELECT version()'Проверка
Команда печатает версию 26.8.
Если не получилось
certificate verify failed— указан не тот файл CA (у Kafka свой CA, он здесь не подходит) или путь вcaConfigневерный.- Подключение висит — сервер в другой сети: ClickHouse без публичного IP доступен только из VPC проекта.
-
Шаг 6. Создайте таблицу Kafka, хранилище и материализованное представление
Таблица на движке Kafka ничего не хранит. Она работает как курсор потребителя: каждое чтение из неё забирает новые сообщения. Поэтому данные складывают в обычную таблицу MergeTree, а перекладывает их материализованное представление — оно срабатывает на каждую пачку сообщений.
В
Kafka(orders_kafka, …)передаются только топик, группа и формат: адрес и учётные данные зафиксированы в интеграции.schema.sqlCREATE TABLE shop.orders_queue ( order_id UInt64, user_id UInt64, amount Decimal(12, 2), ts UInt32 ) ENGINE = Kafka(orders_kafka, kafka_topic_list = 'orders', kafka_group_name = 'clickhouse-orders', kafka_format = 'JSONEachRow'); CREATE TABLE shop.orders ( order_id UInt64, user_id UInt64, amount Decimal(12, 2), created_at DateTime ) ENGINE = MergeTree PARTITION BY toYYYYMM(created_at) ORDER BY (created_at, order_id); CREATE MATERIALIZED VIEW shop.orders_mv TO shop.orders AS SELECT order_id, user_id, amount, toDateTime(ts) AS created_at FROM shop.orders_queue;Как выполнить./clickhouse client --config-file ch.xml --secure --host db.h3llo.cloud --port 9440 \ --user etl --password '<пароль etl>' --database shop --queries-file schema.sqlПроверка
Через несколько секунд в
shop.ordersпоявляются заказы, которые уже лежали в топике (группа новая, чтение с начала):Терминал./clickhouse client --config-file ch.xml --secure --host db.h3llo.cloud --port 9440 \ --user etl --password '<пароль etl>' --query 'SELECT count(), sum(amount) FROM shop.orders'Если не получилось
ACCESS_DENIED … NAMED COLLECTION— пользователь не указан вgrantTo. Добавьте его:h3 api PUT /api/databases/v1/<id ClickHouse>/integrations/orders_kafka/grants -d '{"grantTo":["etl"]}'.- Сообщения не появляются, в
system.kafka_consumersпоявляются ошибки разбора — формат события не совпал со схемой. ДляJSONEachRowимена полей JSON должны совпадать с колонками таблицы Kafka. - Не делайте
SELECTизorders_queueвручную: прочитанные сообщения уйдут из потока и не попадут вorders.
-
Шаг 7. Отправьте события и посмотрите аналитику
Отправьте несколько заказов продюсером из раздела Kafka или прямо через kcat с пользователем, у которого есть право записи в
orders.Тестовое событиеecho '{"order_id":1001,"user_id":7,"amount":1990.00,"ts":'"$(date +%s)"'}' | \ kcat -P -b "<адреса брокеров>" -X security.protocol=SASL_SSL -X sasl.mechanisms=SCRAM-SHA-512 \ -X sasl.username="<логин с правом записи>" -X sasl.password="<пароль>" -X ssl.ca.location=$HOME/kafka-ca.crt -t ordersВыручка по минутамSELECT toStartOfMinute(created_at) AS minute, count() AS orders, sum(amount) AS revenue FROM shop.orders WHERE created_at > now() - INTERVAL 1 HOUR GROUP BY minute ORDER BY minute;Проверка
Новое событие видно в
shop.ordersчерез секунды после отправки.
Проверка результата
Поток работает сам: группа clickhouse-orders читает топик, а таблица растёт. Состояние потребителя видно в системной таблице:
./clickhouse client --config-file ch.xml --secure --host db.h3llo.cloud --port 9440 --user etl --password '<пароль etl>' \
--query "SELECT database, table, num_messages_read, last_exception FROM system.kafka_consumers FORMAT Vertical" Как удалить ресурсы
Удаление базы ClickHouse удаляет её данные. Kafka и топик при этом не меняются.
CLI
h3 db delete <id ClickHouse>
h3 db user delete <id Kafka> <логин clickhouse-…> - Сначала остановите поток:
DROP VIEW shop.orders_mv; DROP TABLE shop.orders_queue;. - Удалите интеграцию:
h3 api DELETE /api/databases/v1/<id ClickHouse>/integrations/orders_kafka. - Базы данных →
analytics→ меню «…» → Удалить. При необходимости удалите и пользователяclickhouseв Kafka.
Типичные ошибки
Можно ли просто указать адрес Kafka и пароль в `ENGINE = Kafka(...)`?
Нет: табличные функции и прямые адреса пользователям не выдаются. К Kafka, PostgreSQL и S3 ClickHouse подключается только через интеграции — так пароли не попадают в DDL, журналы запросов и руки аналитиков.
Как ускорить чтение большого топика?
Добавьте `kafka_num_consumers` (не больше числа партиций топика) и увеличьте число партиций в Kafka. Для ClickHouse с репликами создавайте таблицы с `ON CLUSTER c` и `ReplicatedMergeTree()`.
Что будет с событиями, пока ClickHouse остановлен?
Они остаются в топике в пределах срока хранения (по умолчанию 7 дней). После запуска группа продолжит чтение с сохранённого смещения.
Сколько интеграций можно создать?
До 20 на базу ClickHouse. Одна интеграция Kafka годится для любого числа топиков, на которые у пользователя Kafka есть права.
Связанные продукты и материалы
- Сценарий · 35 минManaged PostgreSQL для приложения: пользователь, pgvector и восстановление на момент времени
- Сценарий · 45 минСайт на облачном сервере: публичный IP, домен и HTTPS
- Сценарий · 40 минПриложение в Managed Kubernetes из своего реестра образов
- Сценарий · 25 минРезервные копии сервера в S3 по расписанию: rclone, cron и ротация
- ПродуктKafka
- ПродуктClickHouse
Сколько стоит
≈ 8,03 ₽ в час · 5 778 ₽ в месяц при работе 24/7
| vCPU ClickHouse | 2 × 1 035 ₽ |
| RAM ClickHouse, ГБ | 4 × 414 ₽ |
| Диск ClickHouse до 20 000 IOPS*, ГБ | 20 × 14,40 ₽ |
| vCPU брокера Kafka | 1 × 900 ₽ |
| RAM брокера Kafka, ГБ | 2 × 360 ₽ |
| Диск брокера до 20 000 IOPS*, ГБ | 10 × 14,40 ₽ |
Интеграции отдельно не оплачиваются. Сервер для SQL-клиента в расчёт не входит: подойдёт уже существующий. Трафик внутри VPC бесплатен.
Цены из прайс-листа, по которому работает биллинг; списание поминутное, месяц — 720 часов. Если удалить ресурсы после проверки, сценарий обойдётся в рубли.
Новым пользователям — 4 000 ₽ на 30 дней на любые сервисы: бонуса хватит, чтобы попробовать этот сценарий целиком. Бонус начисляется после подтверждения телефона и привязки карты.