Передача данных в эндпоинт-приемник ClickHouse®

1. Если вы не планируете использовать для подключения к внешнему кластеру сервис Cloud Interconnect или VPN, разрешите подключения к такому кластеру из интернета с IP-адресов, используемых сервисом Data Transfer.

   Подробнее о настройке сети для работы с внешними ресурсами читайте в концепции.

2. Создайте базу-приемник. Ее имя должно совпадать с именем базы-источника. Если нужно перенести несколько баз данных, создайте для каждой из них отдельный трансфер.

3. Создайте пользователя с доступом к базе приемника.

   После старта трансфер подключится к приемнику от имени этого пользователя.

4. Выдайте созданному пользователю права:

   GRANT CLUSTER ON *.* TO <имя_пользователя>
   GRANT SELECT, INSERT, ALTER DELETE, CREATE TABLE, CREATE VIEW, DROP TABLE, TRUNCATE, dictGet ON <имя_базы_данных>.* TO <имя_пользователя>
   GRANT SELECT(macro, substitution) ON system.macros TO <имя_пользователя>
   

• Тип эндпоинта — clickhouse-target.

• --cluster-id — идентификатор кластера, к которому необходимо подключиться.

• --cluster-name — группа шардов, в которую будут передаваться данные. Если параметр не указан, данные будут размещены во всех шардах.

• --database — имя базы данных.

• --user — имя пользователя, под которым сервис Data Transfer будет подключаться к базе данных.

• --security-group — группы безопасности для сетевого трафика, правила которых применятся к ВМ и кластерам без изменения их настроек. Подробнее читайте в разделе Сеть в Yandex Data Transfer.

  Убедитесь, что указанные группы безопасности настроены.

• Чтобы задать пароль пользователя для доступа к базе данных, используйте один из параметров:

  • --raw-password — пароль в текстовом виде.

  • --password-file — путь к файлу с паролем.

• Тип эндпоинта — clickhouse_target.

• 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_target {
      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 — пароль пользователя для доступа к базе данных (в текстовом виде).

• Тип эндпоинта — clickhouse-target.

• --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_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.

  Важно

  Если не добавить сертификат, трансфер может завершиться ошибкой.

• 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_target {
      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.

    • disabled — отключено.
    • enabled — включено

      • caCertificate — сертификат CA.

        Важно

        Если не добавить сертификат, трансфер может завершиться ошибкой.

  • subnetId — идентификатор подсети, в которой находится хост. Трансфер будет использовать эту подсеть для доступа к хосту.

• clickhouseClusterName — имя кластера, в который будут передаваться данные.

• securityGroups — группы безопасности для сетевого трафика, правила которых применятся к ВМ и кластерам без изменения их настроек. Подробнее читайте в разделе Сеть в Yandex Data Transfer.

• database — имя базы данных.

• user — имя пользователя, под которым сервис Data Transfer будет подключаться к базе данных.

• password.raw — пароль пользователя для доступа к базе данных (в текстовом виде).

• --alt-name — правила переименования таблиц базы-источника при переносе в базу-приемник. Значения указываются в формате <имя_таблицы_в_источнике>:<имя_таблицы_в_приемнике>.

• Настройки шардирования данных:

  • --shard-by-column-hash — имя колонки в таблицах, по которой следует шардировать данные. Равномерное распределение по шардам будет определяться хешем значения этой колонки.

  • --custom-sharding-column-name— имя колонки в таблицах, по которой следует шардировать данные. Шардирование выполняется по значениям колонки, заданным с помощью настройки --custom-sharding-mapping-string.

  • --custom-sharding-mapping-string — сопоставление значений колонки, указанной в настройке --custom-sharding-column-name, и шардов. Значения настройки указываются в формате <значение_колонки>:<имя_шарда>.

  • --shard-by-transfer-id — Данные по шардам будут распределяться на основе значения идентификатора трансфера. Параметр не содержит значения.

  Вы можете указать только один из вариантов шардирования:

  • --shard-by-column-hash;
  • --custom-sharding-column-name и --custom-sharding-mapping-string;
  • --shard-by-transfer-id.

• cleanup_policy — способ очистки данных в базе-приемнике перед переносом:

  • CLICKHOUSE_CLEANUP_POLICY_DISABLED — не очищать (вариант по умолчанию).

    Выберите эту опцию, если будет производиться только репликация без копирования данных.

  • CLICKHOUSE_CLEANUP_POLICY_DROP — полное удаление таблиц, участвующих в трансфере.

    Используйте эту опцию, чтобы при любой активации трансфера в базу-приемник всегда передавалась самая последняя версия схемы таблиц из источника.

  • CLICKHOUSE_CLEANUP_POLICY_TRUNCATE — удалить только данные из таблиц, участвующих в трансфере, но оставить схему.

    Используйте эту опцию, если схема в базе-приемнике отличается от той, которая была бы перенесена из источника при трансфере.

• alt_names — правила переименования таблиц базы-источника при переносе в базу-приемник:

  • from_name — имя таблицы в источнике.
  • to_name — имя таблицы в приемнике.

• Настройки шардирования данных:

  • sharding.column_value_hash.column_name — имя колонки в таблицах, по которой следует шардировать данные. Равномерное распределение по шардам будет определяться хешем значения этой колонки.

  • sharding.transfer_id — данные по шардам распределяются на основе значения идентификатора трансфера. Блок transfer_id не содержит параметров.

  • sharding.custom_mapping — шардирование по значению колонки:

    • column_name — имя колонки в таблицах, по которой следует шардировать данные.

    • mapping — сопоставление значений колонки и шардов:

      • column_value.string_value — значение колонки.
      • shard_name — имя шарда.

  • sharding.round_robin — данные по шардам будут распределяться случайным образом (количество данных на каждом шарде будет примерно одинаковым). Блок round_robin не содержит параметров.

  Вы можете указать только один из вариантов шардирования: sharding.column_value_hash.column_name, sharding.transfer_id, sharding.custom_mapping или sharding.round_robin. Если вариант шардирования не указан, то все данные переносятся в один шард.

• is_schema_migration_disabled — установите значение true, чтобы не изменять схему данных на приемнике при изменении ее на источнике. По умолчанию при изменении схемы на источнике трансфер будет автоматически применять изменения схемы в приемнике: создавать новые таблицы, добавлять новые колонки, добавлять новые перечисляемые значения и перечисляемые типы. По умолчанию не применяются такие изменения, как удаление таблиц или колонок.

• altNames — правила переименования таблиц базы-источника при переносе в базу-приемник.

  • fromName — имя таблицы в источнике.
  • toName — имя таблицы в приемнике.

• cleanupPolicy — способ очистки данных в базе-приемнике перед переносом:

  • CLICKHOUSE_CLEANUP_POLICY_DISABLED — не очищать (вариант по умолчанию).

    Выберите эту опцию, если будет производиться только репликация без копирования данных.

  • CLICKHOUSE_CLEANUP_POLICY_DROP — полное удаление таблиц, участвующих в трансфере.

    Используйте эту опцию, чтобы при любой активации трансфера в базу-приемник всегда передавалась самая последняя версия схемы таблиц из источника.

  • CLICKHOUSE_CLEANUP_POLICY_TRUNCATE — удалить только данные из таблиц, участвующих в трансфере, но оставить схему.

    Используйте эту опцию, если схема в базе-приемнике отличается от той, которая была бы перенесена из источника при трансфере.

• sharding — настройки для шардирования данных. Вы можете указать только один из вариантов шардирования:

  • columnValueHash.columnName — имя колонки в таблицах, по которой следует шардировать данные. Равномерное распределение по шардам будет определяться хешем значения этой колонки.

  • customMapping — шардирование по значению колонки:

    • columnName — имя колонки в таблицах, по которой следует шардировать данные.

    • mapping — сопоставление значений колонки и шардов:

      • columnValue.stringValue — значение колонки.
      • shardName — имя шарда.

  • transferId — данные по шардам будут распределяться на основе значения идентификатора трансфера. Параметр не содержит значения.

  • roundRobin — данные по шардам будут распределяться случайным образом (количество данных на каждом шарде будет примерно одинаковым). Параметр не содержит значения.

  Если вариант шардирования не указан, то все данные переносятся в один шард.

• Если в кластере-приемнике ClickHouse® включено шардирование и перенос выполняется в шардированную таблицу, записывайте данные в локальные таблицы, а не в распределенную таблицу. При этом выполняйте выборку перенесенных данных в приемнике из распределенной таблицы. Чтобы переопределить таблицу для записи, укажите ее в настройке приемника --alt-name.
• Если нужно перенести несколько топиков, укажите в атрибуте --alt-name эндпоинта-приемника для всех топиков источника одно и то же имя таблицы ClickHouse® приемника.

• Если в кластере-приемнике ClickHouse® включено шардирование и перенос выполняется в шардированную таблицу, записывайте данные в локальные таблицы, а не в распределенную таблицу. При этом выполняйте выборку перенесенных данных в приемнике из распределенной таблицы. Чтобы переопределить таблицу для записи, укажите ее в настройке приемника alt_names.to_name.
• Если в источнике вы выбрали формат JSON в блоке parser.json_parser:
  • В схеме данных parser.json_parser.data_schema для строковых типов указывайте UTF-8 вместо STRING.
  • В случае атрибута parser.json_parser.add_rest_column=true скорость трансфера может снизиться.
• Если нужно перенести несколько топиков, укажите в атрибуте alt_names эндпоинта-приемника для всех топиков в alt_names.from_name одно и то же имя таблицы ClickHouse® в alt_names.to_name.

• Если в кластере-приемнике ClickHouse® включено шардирование и перенос выполняется в шардированную таблицу, используйте для записи данных нижележащую таблицу на движке ReplicatedMergeTree, а не распределенную таблицу на движке Distributed. При этом выполняйте выборку перенесенных данных в приемнике из распределенной таблицы. Чтобы переопределить таблицу для записи, укажите ее в настройке приемника altNames.toName.
• Если в источнике вы выбрали формат JSON в блоке parser.jsonParser:
  • В схеме данных parser.jsonParser.dataSchema для строковых типов указывайте UTF-8 вместо STRING.
  • В случае параметра parser.jsonParser.addRestColumn=true скорость трансфера может снизиться.
• Если нужно перенести несколько топиков, укажите в параметре altNames эндпоинта-приемника для всех топиков в altNames.fromName одно и то же имя таблицы ClickHouse® в altNames.toName.