Передача данных из эндпоинта-источника ClickHouse®
С помощью сервиса Yandex Data Transfer вы можете переносить данные из базы ClickHouse® и реализовывать различные сценарии переноса, обработки и трансформации данных. Для реализации трансфера:
- Ознакомьтесь с возможными сценариями передачи данных.
- Подготовьте базу данных ClickHouse® к трансферу.
- Настройте эндпоинт-источник в Yandex Data Transfer.
- Настройте один из поддерживаемых приемников данных.
- Создайте и запустите трансфер.
- Выполняйте необходимые действия по работе с базой и контролируйте трансфер.
- При возникновении проблем, воспользуйтесь готовыми решениями по их устранению.
Сценарии передачи данных из ClickHouse®
Миграция — перенос данных из одного хранилища в другое. Часто это перенос базы из устаревших локальных баз в управляемые облачные.
Подробное описание возможных сценариев передачи данных в Yandex Data Transfer см. в разделе Практические руководства.
Подготовка базы данных источника
Примечание
Yandex Data Transfer не может переносить базы данных ClickHouse®, в названии которых есть дефис.
При переносе таблиц с движками, отличными от движков на базе ReplicatedMergeTree
и Distributed
, в многохостовом кластере ClickHouse® трансфер завершится с ошибкой: the following tables have not Distributed or Replicated engines and are not yet supported
.
-
Убедитесь, что переносимые таблицы используют движки семейства
MergeTree
. Будут перенесены только эти таблицы и материализованные представления (MaterializedView).В случае многохостового кластера будут перенесены таблицы и материализованные представления только с движками на базе
ReplicatedMergeTree
либоDistributed
. Проверьте, что данные таблицы и представления присутствуют на всех хостах кластера. -
Создайте пользователя с доступом к базе источника. В настройках пользователя укажите для параметра Max execution time значение не менее
1000000
.
-
Убедитесь, что переносимые таблицы используют движки семейства
MergeTree
. Будут перенесены только эти таблицы и материализованные представления (MaterializedView).В случае многохостового кластера будут перенесены таблицы и материализованные представления только с движками на базе
ReplicatedMergeTree
либоDistributed
. Проверьте, что данные таблицы и представления присутствуют на всех хостах кластера. -
Убедитесь, что настройки сети, в которой размещен кластер, разрешают подключение к нему из интернета с IP-адресов, используемых сервисом Data Transfer
. -
Создайте пользователя с доступом к базе источника. В настройках пользователя укажите для параметра Max execution time значение не менее
1000000
.
Настройка эндпоинта-источника 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-source
.
-
--cluster-id
— идентификатор кластера, к которому необходимо подключиться. -
--cluster-name
— группа шардов, из которой будут передаваться данные. Если параметр не указан, будут передаваться данные из всех шардов. -
--database
— имя базы данных. -
--user
— имя пользователя, под которым сервис Data Transfer будет подключаться к базе данных. -
--security-group
— группы безопасности для сетевого трафика, правила которых применятся к ВМ и кластерам без изменения их настроек. Подробнее см. в разделе Сеть в Yandex Data Transfer.Убедитесь, что указанные группы безопасности настроены.
-
Чтобы задать пароль пользователя для доступа к базе данных, используйте один из параметров:
-
--raw-password
— пароль в текстовом виде. -
--password-file
— путь к файлу с паролем.
-
- Тип эндпоинта —
clickhouse_source
.
-
connection.connection_options.mdb_cluster_id
— идентификатор кластера, к которому необходимо подключиться. -
clickhouse_cluster_name
— группа шардов, из которой будут передаваться данные. Если параметр не указан, будут передаваться данные из всех шардов. -
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_source {
clickhouse_cluster_name="<группа_шардов>"
security_groups = ["<список_идентификаторов_групп_безопасности>"]
subnet_id = "<идентификатор_подсети>"
connection {
connection_options {
mdb_cluster_id = "<идентификатор_кластера>"
database = "<имя_переносимой_базы_данных>"
user = "<имя_пользователя_для_подключения>"
password {
raw = "<пароль_пользователя>"
}
}
}
<дополнительные_настройки_эндпоинта>
}
}
}
Подробнее см. в документации провайдера Terraform
-
securityGroups
— группы безопасности для сетевого трафика, правила которых применятся к ВМ и кластерам без изменения их настроек. Подробнее см. в разделе Сеть в Yandex Data Transfer.Убедитесь, что указанные группы безопасности настроены.
-
mdbClusterId
— идентификатор кластера, к которому необходимо подключиться. -
clickhouseClusterName
— группа шардов, из которой будут передаваться данные. Если параметр не указан, будут передаваться данные из всех шардов. -
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-source
.
-
--cluster-name
— имя кластера, из которого будут передаваться данные. -
--host
— список IP-адресов или FQDN хостов, к которым необходимо подключиться, в формате{имя_шарда}:{IP-адрес_или_FQDN_хоста}
. Если в пользовательской инсталляции шардирование выключено, укажите произвольное имя шарда. -
http-port
— номер порта, который сервис Data Transfer будет использовать для подключения по HTTP. -
native-port
— номер порта, который сервис Data Transfer будет использовать для подключения к нативному интерфейсу ClickHouse®. -
--ca-certificate
— сертификат CA, если требуется шифрование передаваемых данных, например для соответствия требованиям PCI DSS . -
--subnet-id
— идентификатор подсети, в которой находится хост. -
--database
— имя базы данных. -
--user
— имя пользователя, под которым сервис Data Transfer будет подключаться к базе данных. -
--security-group
— группы безопасности для сетевого трафика, правила которых применятся к ВМ и кластерам без изменения их настроек. Подробнее см. в разделе Сеть в Yandex Data Transfer. -
Чтобы задать пароль пользователя для доступа к базе данных, используйте один из параметров:
-
--raw-password
— пароль в текстовом виде. -
--password-file
— путь к файлу с паролем.
-
- Тип эндпоинта —
clickhouse_source
.
-
Настройки шардов:
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 . clickhouse_cluster_name
— имя кластера, из которого будут передаваться данные.-
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_source {
clickhouse_cluster_name="<имя_кластера>"
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
— параметры подключения к базе данных:-
shards
– настройки шардов:name
— имя шарда, с помощью которого сервис сможет отличать шарды друг от друга. Если в пользовательской инсталляции шардирование выключено, укажите произвольное имя.hosts
— укажите FQDN или IP-адреса хостов, входящих в шард.
-
httpPort
— номер порта, который сервис Data Transfer будет использовать для подключения по HTTP. -
nativePort
— номер порта, который сервис Data Transfer будет использовать для подключения к нативному интерфейсу ClickHouse®. -
tlsMode
— параметры шифрования передаваемых данных, если оно требуется, например для соответствия требованиям PCI DSS . -
subnetId
— идентификатор подсети, в которой находится хост.
-
clickhouseClusterName
— имя кластера, из которого будут передаваться данные.-
securityGroups
— группы безопасности для сетевого трафика, правила которых применятся к ВМ и кластерам без изменения их настроек. Подробнее см. в разделе Сеть в Yandex Data Transfer. -
database
— имя базы данных. -
user
— имя пользователя, под которым сервис Data Transfer будет подключаться к базе данных. -
password.raw
— пароль пользователя для доступа к базе данных (в текстовом виде).
Фильтр таблиц
-
Список включённых таблиц — будут передаваться данные только из таблиц этого списка.
Добавление новых таблиц при редактировании эндпоинта, использующегося в трансферах типа Копирование и репликация или Репликация в статусе Реплицируется, не приведет к загрузке истории данных по этим таблицам. Чтобы добавить таблицу с ее историческими данными, используйте поле Список объектов для переноса в настройках трансфера.
-
Список исключённых таблиц — данные таблиц из этого списка передаваться не будут.
Имена включенных и исключенных таблиц должны соответствовать правилам именования идентификаторов в ClickHouse®. Подробнее читайте в документации ClickHouse®
Оставьте списки пустыми для переноса всех таблиц.
-
--include_table
— список включенных таблиц. Будут передаваться данные только из таблиц этого списка.Добавление новых таблиц при редактировании эндпоинта, использующегося в трансферах типа Копирование и репликация или Репликация в статусе Реплицируется, не приведет к загрузке истории данных по этим таблицам. Чтобы добавить таблицу с ее историческими данными, используйте поле Список объектов для переноса в настройках трансфера.
-
--exclude_table
— список исключенных таблиц. Данные таблиц из этого списка передаваться не будут.
Если списки не указаны, передаются данные из всех таблиц.
-
include_tables
— список включенных таблиц. Будут передаваться данные только из таблиц этого списка.Добавление новых таблиц при редактировании эндпоинта, использующегося в трансферах типа Копирование и репликация или Репликация в статусе Реплицируется, не приведет к загрузке истории данных по этим таблицам. Чтобы добавить таблицу с ее историческими данными, используйте поле Список объектов для переноса в настройках трансфера.
-
exclude_tables
— список исключенных таблиц. Данные таблиц из этого списка передаваться не будут.
Если списки не указаны, передаются данные из всех таблиц.
-
includeTables
— список включенных таблиц. Будут передаваться данные только из таблиц этого списка.Добавление новых таблиц при редактировании эндпоинта, использующегося в трансферах типа Копирование и репликация или Репликация в статусе Реплицируется, не приведет к загрузке истории данных по этим таблицам. Чтобы добавить таблицу с ее историческими данными, используйте поле Список объектов для переноса в настройках трансфера.
-
excludeTables
— список исключенных таблиц. Данные таблиц из этого списка передаваться не будут.
Если списки не указаны, передаются данные из всех таблиц.
Настройка приемника данных
Настройте эндпоинт-приемник:
Полный список поддерживаемых источников и приемников в Yandex Data Transfer см. в разделе Доступные трансферы.
После настройки источника и приемника данных создайте и запустите трансфер.
Решение проблем, возникающих при переносе данных
См. полный список рекомендаций в разделе Решение проблем.
Не добавляются новые таблицы
В трансфер типа Копирование и репликация не добавляются новые таблицы.
Решение:
-
Создайте таблицы в базе-приемнике вручную. Чтобы трансфер работал, при создании таблицы:
-
Добавьте в нее служебные поля трансфера:
__data_transfer_commit_time timestamp, __data_transfer_delete_time timestamp
-
Используйте движок
ReplacingMergeTree
:ENGINE = ReplacingMergeTree
-
-
Создайте отдельный трансфер типа Копирование и репликация и добавьте в список объектов для переноса только новые таблицы. При этом исходный трансфер типа Копирование и репликация можно не деактивировать. Активируйте новый трансфер, а после перехода в статус Реплицируется деактивируйте его.
Чтобы добавить другие таблицы, замените ими список объектов для переноса в созданном отдельном трансфере, вновь активируйте его, а после перехода в статус Реплицируется деактивируйте.
Примечание
Так как два трансфера одновременно переносили данные, то в новых таблицах на приемнике присутствуют дубликаты записей. Чтобы скрыть их, выполните запрос
SELECT * from TABLE <имя_таблицы> FINAL
, а чтобы удалить — запросOPTIMIZE TABLE <имя_таблицы>
.
Не переносятся данные
При попытке перенести данные из источника 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® возвращает ошибку:
TYPE_ERROR [target]: failed to run (abstract1 source): failed to push items from 0 to 1 in batch:
Push failed: failed to push 1 rows to ClickHouse shard 0:
ClickHouse Push failed: Unable to exec changeItem: clickhouse:
dateTime <имя_поля> must be between 1900-01-01 00:00:00 and 2262-04-11 23:47:16
Поддерживаемые диапазоны дат в ClickHouse®:
- Для полей с типом
DateTime64
— с 1900-01-01 по 2299-12-31. Подробнее см. в документации ClickHouse® . - Для полей с типом
DateTime
— с 1970-01-01 по 2106-02-07. Подробнее см. в документации ClickHouse® .
Решение: используйте один из вариантов:
- Приведите все даты в базе-источнике к поддерживаемому в ClickHouse® диапазону.
- В параметрах эндпоинта-источника исключите таблицу с некорректными датами из трансфера.
- В параметрах трансфера укажите трансформер Преобразовать значения в строки. В этом случае при трансфере изменится тип поля.
ClickHouse® является зарегистрированным товарным знаком ClickHouse, Inc