Передача данных в эндпоинт-приемник ClickHouse®
С помощью сервиса Yandex Data Transfer вы можете переносить данные в базу ClickHouse® и реализовывать различные сценарии переноса, обработки и трансформации данных. Для реализации трансфера:
- Ознакомьтесь с возможными сценариями передачи данных.
- Настройте один из поддерживаемых источников данных.
- Подготовьте базу данных ClickHouse® к трансферу.
- Настройте эндпоинт-приемник в Yandex Data Transfer.
- Создайте и запустите трансфер.
- Выполняйте необходимые действия по работе с базой и контролируйте трансфер.
- При возникновении проблем, воспользуйтесь готовыми решениями по их устранению.
Сценарии передачи данных в ClickHouse®
-
Миграция — перенос данных из одного хранилища в другое, часто, перенос базы в облако из устаревших локальных баз в управляемые облачные.
-
Поставка данных — процесс доставки произвольных данных в целевые хранилища. Процесс поставки включает извлечение данных из очереди и их десериализацию с последующей трансформацией данных в формат целевого хранилища.
-
Загрузка данных в витрины — процесс трансфера подготовленных данных в хранилища с целью последующей визуализации.
Подробное описание возможных сценариев передачи данных в Yandex Data Transfer см. в разделе Практические руководства.
Настройка источника данных
Настройте один из поддерживаемых источников данных:
- PostgreSQL;
- MySQL;
- ClickHouse®;
- Greenplum®;
- Apache Kafka®;
- Aibyte;
- Яндекс Метрика;
- YDS;
- Yandex Object Storage;
- Oracle.
- Elasticsearch;
- OpenSearch.
Полный список поддерживаемых источников и приемников в Yandex Data Transfer см. в разделе Доступные трансферы.
Подготовка базы данных приемника
-
Если нужно перенести несколько баз данных, создайте для каждой из них отдельный трансфер.
-
Создайте пользователя с доступом к базе приемника.
После старта трансфер подключится к приемнику от имени этого пользователя.
-
Назначьте кластеру Managed Service for ClickHouse® созданную группу безопасности.
-
Убедитесь, что настройки сети, в которой размещен кластер, разрешают подключение к нему из интернета с IP-адресов, используемых сервисом Data Transfer
. -
Создайте базу-приемник. Ее имя должно совпадать с именем базы-источника. Если нужно перенести несколько баз данных, создайте для каждой из них отдельный трансфер.
-
Создайте пользователя с доступом к базе приемника.
После старта трансфер подключится к приемнику от имени этого пользователя.
Настройка эндпоинта-приемника ClickHouse®
При создании или изменении эндпоинта вы можете задать:
- Настройки подключения к кластеру Yandex Managed Service for ClickHouse® или пользовательской инсталляции, в т. ч. на базе виртуальных машин Yandex Compute Cloud. Эти параметры обязательные.
- Дополнительные параметры.
Кластер Managed Service for ClickHouse®
Важно
Для создания или редактирования эндпоинта управляемой базы данных вам потребуется роль managed-clickhouse.viewer
или примитивная роль viewer
, выданная на каталог кластера этой управляемой базы данных.
Подключение к БД с указанием идентификатора кластера в Yandex Cloud.
-
Managed кластер — идентификатор кластера, к которому необходимо подключиться.
-
Пользователь — укажите имя пользователя, под которым сервис Data Transfer будет подключаться к базе данных.
-
Пароль — укажите пароль пользователя для доступа к базе данных.
-
-
База данных — укажите имя базы данных в выбранном кластере.
-
Группы безопасности — выберите облачную сеть для размещения эндпоинта и группы безопасности для сетевого трафика. Это позволит применить указанные правила групп безопасности к ВМ и кластерам в выбранной сети без изменения их настроек. Подробнее см. в разделе Сеть в Yandex Data Transfer.
Убедитесь, что выбранные группы безопасности настроены.
- Тип эндпоинта —
clickhouse-target
.
-
--cluster-id
— идентификатор кластера, к которому необходимо подключиться. -
--database
— имя базы данных. -
--user
— имя пользователя, под которым сервис Data Transfer будет подключаться к базе данных. -
--security-group
— группы безопасности для сетевого трафика, правила которых применятся к ВМ и кластерам без изменения их настроек. Подробнее см. в разделе Сеть в Yandex Data Transfer.Убедитесь, что указанные группы безопасности настроены.
-
Чтобы задать пароль пользователя для доступа к базе данных, используйте один из параметров:
-
--raw-password
— пароль в текстовом виде. -
--password-file
— путь к файлу с паролем.
-
- Тип эндпоинта —
clickhouse_target
.
-
connection.connection_options.mdb_cluster_id
— идентификатор кластера, к которому необходимо подключиться. -
subnet_id
— идентификатор подсети, в которой находится кластер. Если не указан, то кластер должен быть доступен из интернета.Если значение в этом поле задано для обоих эндпоинтов, то обе подсети должны быть размещены в одной зоне доступности.
-
security_groups
— группы безопасности для сетевого трафика.Правила групп безопасности применяются к трансферу. Они позволяют открыть сетевой доступ с ВМ трансфера к кластеру. Подробнее см. в разделе Сеть в Yandex Data Transfer.
Группы безопасности и подсеть
subnet_id
, если она указана, должны принадлежать той же сети, в которой размещен кластер.Примечание
В Terraform сеть для групп безопасности задавать не нужно.
Убедитесь, что указанные группы безопасности настроены.
-
connection.connection_options.database
— имя базы данных. -
connection.connection_options.user
— имя пользователя, под которым сервис Data Transfer будет подключаться к базе данных. -
connection.connection_options.password.raw
— пароль в текстовом виде.
Пример структуры конфигурационного файла:
resource "yandex_datatransfer_endpoint" "<имя_эндпоинта_в_Terraform>" {
name = "<имя_эндпоинта>"
settings {
clickhouse_target {
security_groups = ["<список_идентификаторов_групп_безопасности>"]
subnet_id = "<идентификатор_подсети>"
connection {
connection_options {
mdb_cluster_id = "<идентификатор_кластера>"
database = "<имя_переносимой_базы_данных>"
user = "<имя_пользователя_для_подключения>"
password {
raw = "<пароль_пользователя>"
}
}
}
<дополнительные_настройки_эндпоинта>
}
}
}
Подробнее см. в документации провайдера Terraform
-
securityGroups
— группы безопасности для сетевого трафика, правила которых применятся к ВМ и кластерам без изменения их настроек. Подробнее см. в разделе Сеть в Yandex Data Transfer.Убедитесь, что указанные группы безопасности настроены.
-
mdbClusterId
— идентификатор кластера, к которому необходимо подключиться. -
database
— имя базы данных. -
user
— имя пользователя, под которым сервис Data Transfer будет подключаться к базе данных. -
password.raw
— пароль пользователя для доступа к базе данных (в текстовом виде).
Пользовательская инсталляция
Подключение к БД с явным указанием сетевых адресов и портов.
-
Шарды
- Шард — укажите строку, которая позволит сервису отличать шарды друг от друга.
- Хосты — укажите FQDN или IP-адреса хостов, входящих в шард.
-
HTTP-порт — укажите номер порта, который сервис Data Transfer будет использовать для подключения.
При подключении через HTTP-порт:
- Для необязательных полей используются значения по умолчанию, если они заданы.
- Поддерживается запись сложных типов (
array
,tuple
и т. д.).
-
Нативный порт — укажите номер нативного порта, который сервис Data Transfer будет использовать для подключения.
-
SSL — включите, если кластер поддерживает только шифрованные соединения.
-
Сертификат CA — если требуется шифрование передаваемых данных, например для соответствия требованиям PCI DSS
, загрузите файл сертификата или добавьте его содержимое в текстовом виде. -
Идентификатор подсети — выберите или создайте подсеть в нужной зоне доступности.
Если значение в этом поле задано для обоих эндпоинтов, то обе подсети должны быть размещены в одной зоне доступности.
-
Пользователь — укажите имя пользователя, под которым сервис Data Transfer будет подключаться к базе данных.
-
Пароль — укажите пароль пользователя для доступа к базе данных.
-
База данных — укажите имя базы данных в выбранном кластере.
-
Группы безопасности — выберите облачную сеть для размещения эндпоинта и группы безопасности для сетевого трафика.
Это позволит применить к ВМ и кластерам в выбранной сети указанные правила групп безопасности без изменения настроек этих ВМ и кластеров. Подробнее см. в разделе Сеть в Yandex Data Transfer.
- Тип эндпоинта —
clickhouse-target
.
-
--host
— IP-адрес или FQDN хоста-мастера, к которому необходимо подключиться. -
--port
— номер порта, который сервис Data Transfer будет использовать для подключения. -
--ca-certificate
— сертификат CA, если требуется шифрование передаваемых данных, например для соответствия требованиям PCI DSS . -
--subnet-id
— идентификатор подсети, в которой находится хост. -
--database
— имя базы данных. -
--user
— имя пользователя, под которым сервис Data Transfer будет подключаться к базе данных. -
--security-group
— группы безопасности для сетевого трафика, правила которых применятся к ВМ и кластерам без изменения их настроек. Подробнее см. в разделе Сеть в Yandex Data Transfer. -
Чтобы задать пароль пользователя для доступа к базе данных, используйте один из параметров:
-
--raw-password
— пароль в текстовом виде. -
--password-file
— путь к файлу с паролем.
-
- Тип эндпоинта —
clickhouse_target
.
-
Настройки шардов:
connection.connection_options.on_premise.shards.name
— имя шарда, с помощью которого сервис сможет отличать шарды друг от друга.connection.connection_options.on_premise.shards.hosts
— укажите FQDN или IP-адреса хостов, входящих в шард.
-
connection.connection_options.on_premise.http_port
— номер порта, который сервис Data Transfer будет использовать для подключения по HTTP. -
connection.connection_options.on_premise.native_port
— номер порта, который сервис Data Transfer будет использовать для подключения к нативному интерфейсу ClickHouse®. -
connection.connection_options.on_premise.tls_mode.enabled.ca_certificate
— сертификат CA, если требуется шифрование передаваемых данных, например, для соответствия требованиям PCI DSS . -
subnet_id
— идентификатор подсети, в которой находится кластер. Если не указан, то кластер должен быть доступен из интернета.Если значение в этом поле задано для обоих эндпоинтов, то обе подсети должны быть размещены в одной зоне доступности.
-
security_groups
— группы безопасности для сетевого трафика.Правила групп безопасности применяются к трансферу. Они позволяют открыть сетевой доступ с ВМ трансфера к ВМ c базой данных. Подробнее см. в разделе Сеть в Yandex Data Transfer.
Группы безопасности должны принадлежать той же сети, что и подсеть
subnet_id
, если она указана.Примечание
В Terraform сеть для групп безопасности задавать не нужно.
-
connection.connection_options.database
— имя базы данных. -
connection.connection_options.user
— имя пользователя, под которым сервис Data Transfer будет подключаться к базе данных. -
connection.connection_options.password.raw
— пароль в текстовом виде.
Пример структуры конфигурационного файла:
resource "yandex_datatransfer_endpoint" "<имя_эндпоинта_в_Terraform>" {
name = "<имя_эндпоинта>"
settings {
clickhouse_target {
security_groups = ["<список_идентификаторов_групп_безопасности>"]
subnet_id = "<идентификатор_подсети>"
connection {
connection_options {
on_premise {
http_port = "<порт_для_подключения_по_HTTP>"
native_port = "<порт_для_подключения_к_нативному_интерфейсу>"
shards {
name = "<имя_шарда>"
hosts = [ "список IP-адресов или FQDN хостов шарда" ]
}
tls_mode {
enabled {
ca_certificate = "<сертификат_в_формате_PEM>"
}
}
}
database = "<имя_переносимой_базы_данных>"
user = "<имя_пользователя_для_подключения>"
password {
raw = "<пароль_пользователя>"
}
}
}
<дополнительные_настройки_эндпоинта>
}
}
}
Подробнее см. в документации провайдера Terraform
onPremise
— параметры подключения к базе данных:-
hosts
— IP-адрес или FQDN хоста-мастера, к которому необходимо подключиться. -
port
— номер порта, который сервис Data Transfer будет использовать для подключения. -
tlsMode
— параметры шифрования передаваемых данных, если оно требуется, например для соответствия требованиям PCI DSS . -
subnetId
— идентификатор подсети, в которой находится хост.
-
-
securityGroups
— группы безопасности для сетевого трафика, правила которых применятся к ВМ и кластерам без изменения их настроек. Подробнее см. в разделе Сеть в Yandex Data Transfer. -
database
— имя базы данных. -
user
— имя пользователя, под которым сервис Data Transfer будет подключаться к базе данных. -
password.raw
— пароль пользователя для доступа к базе данных (в текстовом виде).
Дополнительные настройки
-
Политика очистки — выберите способ очистки данных в базе-приемнике перед переносом:
-
Не очищать
— выберите эту опцию, если будет производиться только репликация без копирования данных. -
Drop
— полное удаление таблиц, участвующих в трансфере (вариант по умолчанию).Используйте эту опцию, чтобы при любой активации трансфера в базу-приемник всегда передавалась самая последняя версия схемы таблиц из источника.
-
Truncate
— удалить только данные из таблиц, участвующих в трансфере, но оставить схему.Используйте эту опцию, если схема в базе-приемнике отличается от той, которая была бы перенесена из источника при трансфере.
-
-
Настройки шардирования — задайте настройки для шардирования:
-
Без шардирования — шардирование не используется.
-
Шардирование по значению колонки — имя колонки в таблицах, по которой следует шардировать данные. Равномерное распределение по шардам будет определяться хешем значения этой колонки. Укажите имя колонки для шардирования в соответствующем поле.
Для шардирования по конкретным значениям колонки укажите их в поле Сопоставление. Это поле определяет соответствие значений колонки и индекса шарда (порядковый номер шарда в отсортированном по именам списке шардов) для шардирования по конкретным значениям данных.
-
Шардирование по идентификатору трансфера — данные по шардам будут распределяться на основе значения идентификатора трансфера. При этом трансфер игнорирует настройку Сопоставление и шардирует данные только по идентификатору трансфера.
Важно
Если не задавать имя колонки для шардирования и не использовать настройку Шардирование по идентификатору трансфера, то все данные будут перенесены в один шард.
-
Равномерное случайное шардирование — данные по шардам будут распределяться случайным образом (количество данных на каждом шарде будет примерно одинаковым).
-
-
Переименование таблиц — при необходимости задайте настройки переименования таблиц при трансфере.
-
Интервал записи — укажите задержку, с которой данные должны поступать в кластер-приемник. Увеличьте значение в этом поле, если ClickHouse® не успевает делать слияние кусков данных.
-
clickhouse_cluster_name
— укажите имя кластера, в который будут передаваться данные. -
alt_names
— при необходимости укажите правила переименования таблиц базы-источника при переносе в базу-приемник:from_name
– имя таблицы в источнике.to_name
– имя таблицы в приемнике.
-
sharding.column_value_hash.column_name
— имя колонки в таблицах, по которой следует шардировать данные. Равномерное распределение по шардам будет определяться хешем значения этой колонки. -
sharding.transfer_id
— при значенииtrue
данные по шардам распределяются на основе значения идентификатора трансфера. При этом трансфер игнорирует настройкуsharding.column_value_hash.column_name
и шардирует данные только по идентификатору трансфера.Важно
Если не задавать имя колонки для шардирования и не использовать настройку
sharding.transfer_id
, то все данные будут перенесены в один шард. -
cleanup_policy
— укажите способ очистки данных в базе-приемнике перед переносом:-
CLICKHOUSE_CLEANUP_POLICY_DROP
— полное удаление таблиц, участвующих в трансфере (вариант по умолчанию).Используйте эту опцию, чтобы при любой активации трансфера в базу-приемник всегда передавалась самая последняя версия схемы таблиц из источника.
-
CLICKHOUSE_CLEANUP_POLICY_DISABLED
— не очищать.Выберите эту опцию, если будет производиться только репликация без копирования данных.
-
После настройки источника и приемника данных создайте и запустите трансфер.
Решение проблем, возникающих при переносе данных
См. полный список рекомендаций в разделе Решение проблем.
Не добавляются новые таблицы
В трансфер типа Копирование и репликация не добавляются новые таблицы.
Решение:
- Деактивируйте и активируйте трансфер повторно.
- Создайте таблицу в базе-приемнике вручную.
- Создайте отдельный трансфер типа Копирование и добавьте в него только вновь созданные таблицы. При этом исходный трансфер типа Копирование и репликация можно не деактивировать.
Не переносятся данные
При попытке перенести данные из источника ClickHouse® выводится ошибка:
Syntax error: failed at position 25 ('-'): <детали_ошибки>. Expected one of: token, Dot, UUID, alias, AS, identifier, FINAL, SAMPLE, INTO OUTFILE, FORMAT, SETTINGS, end of query
Решение:
Yandex Data Transfer не может переносить базы данных, в названии которых есть дефис. Переименуйте базу данных, если есть такая возможность.
ClickHouse® является зарегистрированным товарным знаком ClickHouse, Inc