Перейти к основному содержимому
Перейти к основному содержимому

JDBC Коннектор

примечание

Этот коннектор следует использовать только в том случае, если ваши данные просты и состоят из примитивных типов данных, например, int. Специфические для ClickHouse типы, такие как карты, не поддерживаются.

В наших примерах мы используем Confluent-распределение Kafka Connect.

Ниже мы описываем простую установку, извлекая сообщения из одной темы Kafka и вставляя строки в таблицу ClickHouse. Мы рекомендуем Confluent Cloud, который предлагает щедрый бесплатный уровень для тех, у кого нет окружения Kafka.

Обратите внимание, что для JDBC Коннектора требуется схема (вы не можете использовать простой JSON или CSV с JDBC коннектором). Хотя схема может быть закодирована в каждом сообщении; настойчиво рекомендуется использовать реестр схем Confluenty, чтобы избежать связанных накладных расходов. Предоставляемый скрипт вставки автоматически выводит схему из сообщений и добавляет ее в реестр - этот скрипт можно повторно использовать для других наборов данных. Ключи Kafka предполагаются строками. Дополнительные сведения о схемах Kafka можно найти здесь.

Лицензия​

JDBC Коннектор распространяется по условиям Confluent Community License

Шаги​

Соберите ваши данные для подключения​

Чтобы подключиться к ClickHouse с помощью HTTP(S), вам нужна следующая информация:

  • ХОСТ и ПОРТ: обычно порт 8443 при использовании TLS или 8123 при его отсутствии.

  • НАЗВАНИЕ БАЗЫ ДАННЫХ: по умолчанию есть база данных с именем default, используйте имя базы данных, к которой вы хотите подключиться.

  • ИМЯ ПОЛЬЗОВАТЕЛЯ и ПАРОЛЬ: по умолчанию имя пользователя default. Используйте имя пользователя, подходящее для вашего случая использования.

Данные для вашей службы ClickHouse Cloud доступны в консоли ClickHouse Cloud. Выберите службу, к которой вы будете подключаться, и нажмите Подключиться:

Кнопка подключения к службе ClickHouse Cloud

Выберите HTTPS, и детали будут доступны в примере команды curl.

Детали подключения ClickHouse Cloud через HTTPS

Если вы используете self-managed ClickHouse, детали подключения задаются вашим администратором ClickHouse.

1. Установите Kafka Connect и Коннектор​

Мы предполагаем, что вы загрузили пакет Confluent и установили его локально. Следуйте инструкциям по установке коннектора, как описано здесь.

Если вы используете метод установки confluent-hub, ваши локальные конфигурационные файлы будут обновлены.

Для отправки данных в ClickHouse из Kafka мы используем компонент Sink коннектора.

2. Загрузите и установите JDBC Драйвер​

Загрузите и установите JDBC драйвер ClickHouse clickhouse-jdbc-<version>-shaded.jar отсюда. Установите его в Kafka Connect, следуя подробностям здесь. Другие драйверы могут работать, но не были протестированы.

примечание

Общая проблема: документация предлагает скопировать jar в share/java/kafka-connect-jdbc/. Если у вас возникли проблемы с тем, чтобы Connect находил драйвер, скопируйте драйвер в share/confluent-hub-components/confluentinc-kafka-connect-jdbc/lib/. Или измените plugin.path, чтобы включить драйвер - см. ниже.

3. Подготовьте Конфигурацию​

Следуйте этим инструкциям для настройки Connect в соответствии с типом вашей установки, отмечая различия между отдельным и распределенным кластером. Если вы используете Confluent Cloud, распределенная настройка является актуальной.

Следующие параметры относятся к использованию JDBC коннектора с ClickHouse. Полный список параметров можно найти здесь:

  • _connection.url_ - это должно принимать форму jdbc:clickhouse://&lt;clickhouse host>:&lt;clickhouse http port>/&lt;target database>
  • connection.user - пользователь с правами записи в целевую базу данных
  • table.name.format - таблица ClickHouse для вставки данных. Она должна существовать.
  • batch.size - количество строк, отправляемых в одной партии. Убедитесь, что это значение установлено на соответствующее большое число. В соответствии с рекомендациями ClickHouse минимальное значение должно быть 1000.
  • tasks.max - JDBC Sink коннектор поддерживает выполнение одной или нескольких задач. Это может быть использовано для увеличения производительности. Вместе с размером партии это представляется вашим основным средством для улучшения производительности.
  • value.converter.schemas.enable - Установите в false, если используете реестр схем, true, если вы встраиваете свои схемы в сообщения.
  • value.converter - Установите в соответствии с вашим типом данных, например для JSON, io.confluent.connect.json.JsonSchemaConverter.
  • key.converter - Установите на org.apache.kafka.connect.storage.StringConverter. Мы используем строковые ключи.
  • pk.mode - Не актуально для ClickHouse. Установите в none.
  • auto.create - Не поддерживается и должно быть false.
  • auto.evolve - Мы рекомендуем false для этой настройки, хотя она может быть поддержана в будущем.
  • insert.mode - Установите на "insert". Другие режимы в настоящее время не поддерживаются.
  • key.converter - Установите в соответствии с типами ваших ключей.
  • value.converter - Установите на основе типа данных в вашей теме. Эти данные должны иметь поддерживаемую схему - в форматах JSON, Avro или Protobuf.

Если вы используете наш образец данных для тестирования, убедитесь, что следующие параметры установлены:

  • value.converter.schemas.enable - Установите в false, так как мы используем реестр схем. Установите в true, если вы встраиваете схему в каждое сообщение.
  • key.converter - Установите на "org.apache.kafka.connect.storage.StringConverter". Мы используем строковые ключи.
  • value.converter - Установите на "io.confluent.connect.json.JsonSchemaConverter".
  • value.converter.schema.registry.url - Установите на URL сервера схемы вместе с учетными данными для сервера схемы через параметр value.converter.schema.registry.basic.auth.user.info.

Пример конфигурационных файлов для образца данных Github можно найти здесь, при условии, что Connect запускается в автономном режиме, а Kafka размещен в Confluent Cloud.

4. Создайте таблицу ClickHouse​

Убедитесь, что таблица была создана, удалив ее, если она уже существует из предыдущих примеров. Пример, совместимый с уменьшенным набором данных Github, показан ниже. Обратите внимание на отсутствие любых типов Array или Map, которые в настоящее время не поддерживаются:

5. Запустите Kafka Connect​

Запустите Kafka Connect в режиме автономной или распределенной работы.

6. Добавьте данные в Kafka​

Вставьте сообщения в Kafka, используя скрипт и конфигурацию, предоставленные. Вам нужно будет изменить github.config, чтобы включить ваши учетные данные Kafka. Скрипт в настоящее время настроен для использования с Confluent Cloud.

Этот скрипт можно использовать для вставки любого ndjson файла в тему Kafka. Это попытается автоматически вывести схему для вас. Образец конфигурации, предоставленный, будет вставлять только 10k сообщений - измените здесь, если это необходимо. Эта конфигурация также удаляет любые несовместимые полевые массивы из набора данных во время вставки в Kafka.

Это необходимо для того, чтобы JDBC коннектор мог преобразовывать сообщения в операторы INSERT. Если вы используете свои данные, убедитесь, что вы вставляете схему с каждым сообщением (установив _value.converter.schemas.enable _в true) или обеспечиваете, чтобы ваш клиент публиковал сообщения с ссылкой на схему в реестр.

Kafka Connect должен начать получать сообщения и вставлять строки в ClickHouse. Обратите внимание, что предупреждения относительно "[JDBC Compliant Mode] Transaction is not supported." ожидаемы и могут быть проигнорированы.

Простое чтение из целевой таблицы "Github" должно подтвердить вставку данных.