Передача данных из эндпоинта-источника ClickHouse®
С помощью сервиса Yandex Data Transfer вы можете переносить данные из базы ClickHouse® и реализовывать различные сценарии переноса, обработки и трансформации данных. Для реализации трансфера:
- Ознакомьтесь с возможными сценариями передачи данных.
- Подготовьте базу данных ClickHouse® к трансферу.
- Настройте эндпоинт-источник в Yandex Data Transfer.
- Настройте один из поддерживаемых приемников данных.
- Создайте и запустите трансфер.
- Выполняйте необходимые действия по работе с базой и контролируйте трансфер.
- При возникновении проблем, воспользуйтесь готовыми решениями по их устранению.
Сценарии передачи данных из ClickHouse®
Миграция — перенос данных из одного хранилища в другое, часто, перенос базы в облако из устаревших локальных баз в управляемые облачные.
Подробное описание возможных сценариев передачи данных в Yandex Data Transfer см. в разделе Практические руководства.
Подготовка базы данных источника
- Убедитесь, что переносимые таблицы используют движки семейства
MergeTree
. Будут перенесены только эти таблицы и материализованные представления (MaterializedView). - Создайте пользователя с доступом к базе источника. В настройках пользователя укажите для параметра Max execution time значение не менее
1000000
.
-
Убедитесь, что переносимые таблицы используют движки семейства
MergeTree
. Будут перенесены только эти таблицы и материализованные представления (MaterializedView). -
Убедитесь, что настройки сети, в которой размещен кластер, разрешают подключение к нему из интернета с 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
— идентификатор кластера, к которому необходимо подключиться. -
--database
— имя базы данных. -
--user
— имя пользователя, под которым сервис Data Transfer будет подключаться к базе данных. -
--security-group
— группы безопасности для сетевого трафика, правила которых применятся к ВМ и кластерам без изменения их настроек. Подробнее см. в разделе Сеть в Yandex Data Transfer.Убедитесь, что указанные группы безопасности настроены.
-
Чтобы задать пароль пользователя для доступа к базе данных, используйте один из параметров:
-
--raw-password
— пароль в текстовом виде. -
--password-file
— путь к файлу с паролем.
-
- Тип эндпоинта —
clickhouse_source
.
-
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_source {
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-source
.
-
--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_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 . -
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 {
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
— пароль пользователя для доступа к базе данных (в текстовом виде).
Фильтр таблиц
-
Список включённых таблиц — будут передаваться данные только из таблиц этого списка.
Добавление новых таблиц при редактировании эндпоинта, использующегося в трансферах типа Копирование и репликация или Репликация в статусе Реплицируется, не приведет к загрузке истории данных по этим таблицам. Чтобы добавить таблицу с ее историческими данными, используйте поле Список объектов для переноса в настройках трансфера.
-
Список исключённых таблиц — данные таблиц из этого списка передаваться не будут.
Списки включают имя схемы (описание содержания, структуры и ограничений целостности базы данных) и имя таблицы. Для обоих списков поддерживаются выражения вида:
<имя_схемы>.<имя_таблицы>
— полное имя таблицы;<имя_схемы>.*
— все таблицы в указанной схеме;<имя_таблицы>
— таблица в схеме по умолчанию.
Имена включенных и исключенных таблиц должны соответствовать правилам именования идентификаторов в ClickHouse®. Подробнее читайте в документации ClickHouse®
Оставьте списки пустыми для переноса всех таблиц.
-
include_tables
— список включенных таблиц. Будут передаваться данные только из таблиц этого списка.Добавление новых таблиц при редактировании эндпоинта, использующегося в трансферах типа Копирование и репликация или Репликация в статусе Реплицируется, не приведет к загрузке истории данных по этим таблицам. Чтобы добавить таблицу с ее историческими данными, используйте поле Список объектов для переноса в настройках трансфера.
-
exclude_tables
— список исключенных таблиц. Данные таблиц из этого списка передаваться не будут.
Списки включают имя схемы (описание содержания, структуры и ограничений целостности базы данных) и имя таблицы. Для обоих списков поддерживаются выражения вида:
<имя_схемы>.<имя_таблицы>
— полное имя таблицы;<имя_схемы>.*
— все таблицы в указанной схеме;<имя_таблицы>
— таблица в схеме по умолчанию.
Известные ограничения
Если таблицы источника ClickHouse® будут содержать колонки следующих типов, трансфер завершится с ошибкой:
Тип | Пример ошибки |
---|---|
Int128 |
unhandled type Int128 |
Int256 |
unhandled type Int256 |
UInt128 |
unhandled type UInt128 |
UInt256 |
unhandled type UInt256 |
Bool |
unhandled type Bool |
Date32 |
unhandled type Date32 |
JSON |
unhandled type '<имя_поля> <название_типа>' |
Array(Date) |
Can't transfer type 'Array(Date)', column '<имя_колонки>' |
Array(DateTime) |
Can't transfer type 'Array(DateTime)', column '<имя_колонки>' |
Array(DateTime64) |
Can't transfer type 'Array(DateTime64)', column '<имя_колонки>' |
Map(,) |
unhandled type Map(<название_типа>, <название_типа>) |
Поддерживаемые виды таблиц
Если кластер ClickHouse® содержит более одного хоста, трансфер поддерживает перенос таблиц и материализованных представлений только с движками на базе ReplicatedMergeTree
либо Distributed
. Также, данные таблицы и представления должны присутствовать на всех хостах кластера.
В случае, если в списке включенных таблиц присутствуют таблицы или представления с другими движками, либо они присутствуют не на всех хостах кластера — трансфер завершится с ошибкой: the following tables have not Distributed or Replicated engines and are not yet supported
.
Имена баз данных
Yandex Data Transfer не может переносить базы данных ClickHouse®, в названии которых есть дефис.
Настройка приемника данных
Настройте эндпоинт-приемник:
Полный список поддерживаемых источников и приемников в Yandex Data Transfer см. в разделе Доступные трансферы.
После настройки источника и приемника данных создайте и запустите трансфер.
Решение проблем, возникающих при переносе данных
См. полный список рекомендаций в разделе Решение проблем.
Не добавляются новые таблицы
В трансфер типа Копирование и репликация не добавляются новые таблицы.
Решение:
- Деактивируйте и активируйте трансфер повторно.
- Создайте таблицу в базе-приемнике вручную.
- Создайте отдельный трансфер типа Копирование и добавьте в него только вновь созданные таблицы. При этом исходный трансфер типа Копирование и репликация можно не деактивировать.
Не переносятся данные
При попытке перенести данные из источника 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