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

Подключение ClickHouse к внешним источникам данных с помощью JDBC

Примечание

Использование JDBC требует ClickHouse JDBC Bridge, поэтому вам понадобится использовать clickhouse-local на локальной машине, чтобы передавать данные из вашей базы данных в ClickHouse Cloud. Перейдите на страницу Using clickhouse-local в разделе Migrate документации для получения подробной информации.

Обзор: ClickHouse JDBC Bridge в сочетании с табличной функцией jdbc или табличным движком JDBC позволяет ClickHouse получать доступ к данным из любого внешнего источника данных, для которого доступен JDBC-драйвер:

Схема архитектуры ClickHouse JDBC Bridge

Это удобно, когда для внешнего источника данных нет встроенного интеграционного движка, табличной функции или внешнего словаря, но существует JDBC-драйвер для этого источника данных.

Вы можете использовать ClickHouse JDBC Bridge как для чтения, так и для записи, и параллельно — для нескольких внешних источников данных; например, вы можете выполнять распределённые запросы в ClickHouse по нескольким внешним и внутренним источникам данных в режиме реального времени.

В этом уроке мы покажем, насколько просто установить, настроить и запустить ClickHouse JDBC Bridge для подключения ClickHouse к внешнему источнику данных. В качестве внешнего источника данных в этом уроке мы будем использовать MySQL.

Приступим!

Предварительные требования

У вас есть доступ к машине, на которой:

  1. установлена оболочка Unix и есть доступ в интернет
  2. установлен wget
  3. установлена актуальная версия Java (например, OpenJDK версии >= 17)
  4. установлена и запущена актуальная версия MySQL (например, MySQL версии >= 8)
  5. установлена и запущена актуальная версия ClickHouse (см. установку)

Установка ClickHouse JDBC Bridge локально​

Самый простой способ использовать ClickHouse JDBC Bridge — установить и запустить его на той же машине, где работает ClickHouse:

Схема локального развертывания ClickHouse JDBC Bridge

Начнём с подключения к командной оболочке Unix на машине, где запущен ClickHouse, и создания локальной папки, в которую мы позже установим ClickHouse JDBC Bridge (можно назвать папку как угодно и разместить её в любом удобном месте):

mkdir ~/clickhouse-jdbc-bridge

Теперь загрузим текущую версию ClickHouse JDBC Bridge в эту папку:

cd ~/clickhouse-jdbc-bridge
wget https://github.com/ClickHouse/clickhouse-jdbc-bridge/releases/download/v2.0.7/clickhouse-jdbc-bridge-2.0.7-shaded.jar

Чтобы подключиться к MySQL, создадим именованный источник данных:

cd ~/clickhouse-jdbc-bridge
mkdir -p config/datasources
touch config/datasources/mysql8.json

Теперь вы можете скопировать и вставить следующую конфигурацию в файл ~/clickhouse-jdbc-bridge/config/datasources/mysql8.json:

{
  "mysql8": {
  "driverUrls": [
    "https://repo1.maven.org/maven2/mysql/mysql-connector-java/8.0.28/mysql-connector-java-8.0.28.jar"
  ],
  "jdbcUrl": "jdbc:mysql://<host>:<port>",
  "username": "<username>",
  "password": "<password>"
  }
}
Примечание

в конфигурационном файле выше

  • вы можете использовать любое имя для источника данных, мы использовали mysql8
  • в значении jdbcUrl вам нужно заменить <host> и <port> на соответствующие значения для запущенного экземпляра MySQL, например "jdbc:mysql://localhost:3306"
  • вам нужно заменить <username> и <password> на ваши учётные данные MySQL; если вы не используете пароль, вы можете удалить строку "password": "<password>" в конфигурационном файле выше
  • в значении driverUrls мы просто указали URL, по которому можно скачать текущую версию JDBC‑драйвера MySQL. На этом всё — ClickHouse JDBC Bridge автоматически скачает этот JDBC‑драйвер (в зависящий от ОС каталог).

Теперь мы готовы запустить ClickHouse JDBC Bridge:

cd ~/clickhouse-jdbc-bridge
java -jar clickhouse-jdbc-bridge-2.0.7-shaded.jar
Примечание

Мы запустили ClickHouse JDBC Bridge в режиме переднего плана. Чтобы остановить Bridge, вы можете вернуть показанное выше окно оболочки Unix на передний план и нажать CTRL+C.

Использование JDBC-подключения из ClickHouse​

Теперь ClickHouse может получать доступ к данным MySQL с помощью табличной функции jdbc или движка таблицы JDBC.

Самый простой способ выполнить следующие примеры — скопировать и вставить их в clickhouse-client или в Play UI.

  • Табличная функция jdbc:
SELECT * FROM jdbc('mysql8', 'mydatabase', 'mytable');
Примечание

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

  • Табличный движок JDBC:
CREATE TABLE mytable (
     <column> <column_type>,
     ...
)
ENGINE = JDBC('mysql8', 'mydatabase', 'mytable');

SELECT * FROM mytable;
Примечание

В качестве первого параметра в секции движка jdbc мы используем имя именованного источника данных, который мы настроили выше.

Схема таблицы движка ClickHouse JDBC и схема подключённой таблицы MySQL должны быть согласованы: например, имена и порядок столбцов должны совпадать, а типы данных столбцов — быть совместимыми.

Внешняя установка ClickHouse JDBC Bridge​

Для распределённого кластера ClickHouse (кластера с более чем одним хостом ClickHouse) имеет смысл установить и запускать ClickHouse JDBC Bridge отдельно, на выделенном хосте:

Схема внешнего развертывания ClickHouse JDBC Bridge

Преимущество такого подхода в том, что каждый хост ClickHouse может обращаться к JDBC Bridge. В противном случае JDBC Bridge пришлось бы устанавливать локально на каждый экземпляр ClickHouse, который должен обращаться к внешним источникам данных через Bridge.

Для внешней установки ClickHouse JDBC Bridge выполните следующие шаги:

  1. Установите, настройте и запустите ClickHouse JDBC Bridge на выделенном хосте, следуя шагам, описанным в разделе 1 данного руководства.

  2. На каждом хосте ClickHouse добавьте следующий блок конфигурации в конфигурацию сервера ClickHouse (в зависимости от выбранного формата конфигурации используйте XML- или YAML-вариант):

<jdbc_bridge>
   <host>JDBC-Bridge-Host</host>
   <port>9019</port>
</jdbc_bridge>
Примечание
  • необходимо заменить JDBC-Bridge-Host на имя хоста или IP-адрес выделенного хоста ClickHouse JDBC Bridge
  • указан порт ClickHouse JDBC Bridge по умолчанию 9019; если вы используете для JDBC Bridge другой порт, необходимо соответствующим образом изменить конфигурацию выше