JDBC Bridge

Елена Дворядкина

Содержание

Установка
Настройка
Использование
- Табличная функция jdbc
- Движок таблиц JDBC
Пример

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

Установка

ClickHouse JDBC Bridge в ADQM — это компонент сервиса ADQMDB, который устанавливается так же, как другие компоненты. В статье Добавление компонентов подробно описаны действия, которые необходимо выполнить, чтобы развернуть компоненты ADQM на хостах кластера через интерфейс ADCM.

ВАЖНО

При установке компонента ClickHouse JDBC Bridge его необходимо добавить на все хосты кластера, где установлен компонент Clickhouse Server.

Настройка

Для подключения ADQM к внешнему источнику данных (data source) через JDBC Bridge нужно добавить описание этого источника под некоторым именем в поле datasource.json, которое находится на странице конфигурации сервиса ADQMDB в секции JDBC Bridge configuration (секция доступна при включенной опции Show advanced) интерфейса ADCM.

По умолчанию в конфигурации JDBC Bridge прописаны два источника данных (postgres13 для PostgreSQL и ch-server для ClickHouse):

[
    {
        "$schema": "./datasource.jschema",
        "postgres13": {
            "converter": {
                "mappings": [
                    {
                        "nativeType": "bool",
                        "toType": "String"
                    }
                ]
            },
            "driverUrls": [
                "drivers/postgresql/postgresql-jdbc.jar"
            ],
            "driverClassName": "org.postgresql.Driver",
            "jdbcUrl": "jdbc:postgresql://localhost/test",
            "username": "",
            "password": "",
            "initializationFailTimeout": 0,
            "minimumIdle": 0,
            "maximumPoolSize": 10
        }
    },
    {
        "$schema": "./datasource.jschema",
        "ch-server": {
            "driverUrls": [
                "drivers/clickhouse/clickhouse-jdbc.jar"
            ],
            "driverClassName": "ru.yandex.clickhouse.ClickHouseDriver",
            "jdbcUrl": "jdbc:clickhouse://ch-server:8123/system",
            "username": "default",
            "password": "",
            "initializationFailTimeout": 0,
            "minimumIdle": 0,
            "maximumPoolSize": 10
        }
    }
]

Эти конфигурации можно изменить или использовать как шаблоны для описания новых источников данных, соблюдая формат JSON. Например, для PostgreSQL необходимо указать реальные значения username и password, а также в значении ключа jdbcUrl заменить localhost на хост, на котором установлен PostgreSQL, и test — на нужную базу данных.

Для удобства ниже приведен шаблон конфигурации источника данных в общем виде — вы можете его скопировать и вставить в поле datasource.json, заполнив реальными данными для внешней СУБД:

{
  "<datasource_name>": {
  "driverUrls": [
    "<datasource_jdbc_driver_url>"
  ],
  "jdbcUrl": "jdbc:<driver_name>://<host>:<port>/<database>",
  "username": "<username>",
  "password": "<password>"
  }
}

где:

<datasource_name> — произвольное имя источника данных, которое будет использоваться при указании источника в табличной функции jdbc или при создании таблицы на базе движка JDBC;
<datasource_jdbc_driver_url> — URL-адрес, с которого можно загрузить JDBC-драйвер для соответствующей СУБД;
<driver_name> — название драйвера;
<host>:<port> — хост и порт, где установлена СУБД;
<database> — имя базы данных в СУБД (данный элемент не является обязательным — если его пропустить, базу данных нужно будет явно указывать при каждом подключении ADQM к внешнему источнику данных);
<username> и <password> — учетные данные для доступа в СУБД.

ВАЖНО

После завершения редактирования конфигурации не забудьте нажать Save и выполнить действие Reconfig and restart для сервиса ADQMDB, чтобы сохранить изменения и перезапустить сервис.

Получить список именованных источников данных, настроенных для JDBC Bridge, можно с помощью следующего запроса:

SELECT name FROM jdbc('', 'show datasources');

Пример вывода на экран:

┌─name────────┐
│ ch-server   │
│ self_server │
│ postgres13  │
│ script      │
└─────────────┘

Использование

Взаимодействие ADQM с внешней СУБД по JDBC-интерфейсу осуществляется через табличную функцию jdbc или табличный движок JDBC.

Табличная функция jdbc

Табличная функция jdbc возвращает таблицу, подключенную к внешнему источнику данных через JDBC-драйвер. Базовый синтаксис запроса с вызовом функции:

SELECT ... FROM jdbc('<datasource>', ['<external_database_name | schema>'], '<external_table_name | query>');

где:

<datasource> — имя внешнего источника данных, указанное в конфигурации JDBC Bridge;
<external_database_name | schema> — имя базы данных во внешнем источнике или схема таблицы (необязательный параметр);
<external_table_name | query> — имя таблицы во внешней базе данных или запрос на выборку данных из внешней таблицы в нативном формате внешнего источника данных.

Движок таблиц JDBC

Для интеграции с внешним источниками данных через JDBC-интерфейс можно также использовать специальный табличный движок — JDBC. Синтаксис запроса для создания таблицы на базе этого движка в общем виде:

CREATE TABLE [IF NOT EXISTS] [<db_name>.]<jdbc_table_name> (<column_name> <column_type>, ...)
ENGINE = JDBC('<datasource>', '<external_database_name>', '<external_table_name | query>');

где:

<column_name> <column_type>, … — описание столбцов таблицы (схема таблицы должна быть согласована со схемой внешней таблицы <external_table_name>, к которой осуществляется подключение, или с таблицей, которую возвращает запрос <query> — то есть имена и порядок столбцов должны быть одинаковыми, а типы столбцов должны быть совместимыми);
<datasource> — имя внешнего источника данных, указанное в конфигурации JDBC Bridge;
<external_db_name> — имя базы данных во внешнем источнике (оставьте этот параметр пустым — '', если имя базы данных прописано в конфигурации источника данных или явно указывается в запросе <query>, передаваемом в качестве третьего параметра движка JDBC);
<external_table_name | query> — имя таблицы в базе данных external_db_name или запрос на выборку данных из внешней таблицы (например, SELECT * FROM test_table WHERE column_1 = 1).

Пример

На сервере MariaDB создайте таблицу в базе данных mariadb_db:

CREATE TABLE mariadb_table (id INT PRIMARY KEY, date DATETIME);

Вставьте в таблицу тестовые данные:

INSERT INTO mariadb_table VALUES (1, "2023-09-25 11:12:13"), (2, "2023-09-26 12:13:14"), (3, "2023-09-27 13:14:15");

В текст параметра datasource.json конфигурации JDBC Bridge добавьте следующее описание источника данных MariaDB (замените <host>:<port> на адрес сервера MariaDB, а <user_name> и <user_password> на имя пользователя и пароль для доступа к базе данных MariaDB):
{ "$schema": "./datasource.jschema", "mariadb10": { "driverUrls": [ "https://repo1.maven.org/maven2/org/mariadb/jdbc/mariadb-java-client/2.7.4/mariadb-java-client-2.7.4.jar" ], "driverClassName": "org.mariadb.jdbc.Driver", "jdbcUrl": "jdbc:mariadb://<host>:<port>", "dataSource": { "user": "<user_name>", "password": "<user_password>" }, "initializationFailTimeout": 0, "minimumIdle": 0, "maximumPoolSize": 10 } }
Нажмите Save и выполните действие Reconfig and restart для сервиса ADQMDB, чтобы сохранить информацию об источнике данных MariaDB в конфигурации JDBC Bridge и перезапустить сервис.

Описание источника данных для JDBC Bridge

Подключитесь из ADQM к таблице mariadb_table внешней базы данных mariadb_db с помощью табличной функции или табличного движка JDBC, используя в обоих случаях имя сконфигурированного выше источника данных в качестве значения первого параметра.

Табличная функция jdbc:

SELECT * FROM jdbc('mariadb10', 'mariadb_db', 'mariadb_table');

┌─id─┬────────────────date─┐
│  1 │ 2023-09-25 11:12:13 │
│  2 │ 2023-09-26 12:13:14 │
│  3 │ 2023-09-27 13:14:15 │
└────┴─────────────────────┘

SELECT * FROM jdbc('mariadb10', 'SELECT * FROM mariadb_db.mariadb_table WHERE id >= 2');

┌─id─┬────────────────date─┐
│  2 │ 2023-09-26 12:13:14 │
│  3 │ 2023-09-27 13:14:15 │
└────┴─────────────────────┘

SELECT * FROM jdbc('mariadb10', 'test_dates DateTime', 'SELECT date as test_dates FROM mariadb_db.mariadb_table');

┌──────────test_dates─┐
│ 2023-09-25 11:12:13 │
│ 2023-09-26 12:13:14 │
│ 2023-09-27 13:14:15 │
└─────────────────────┘

Табличный движок JDBC:

CREATE TABLE jdbc_table (id Int32, date DateTime) ENGINE JDBC('mariadb10', 'mariadb_db', 'mariadb_table');

SELECT * FROM jdbc_table;

┌─id─┬────────────────date─┐
│  1 │ 2023-09-25 11:12:13 │
│  2 │ 2023-09-26 12:13:14 │
│  3 │ 2023-09-27 13:14:15 │
└────┴─────────────────────┘

CREATE TABLE jdbc_table_1 (test_IDs Int32, test_dates DateTime)
ENGINE JDBC('mariadb10', '', 'SELECT id as test_IDs, date as test_dates FROM mariadb_db.mariadb_table');

SELECT * FROM jdbc_table_1;

┌─test_IDs─┬──────────test_dates─┐
│        1 │ 2023-09-25 11:12:13 │
│        2 │ 2023-09-26 12:13:14 │
│        3 │ 2023-09-27 13:14:15 │
└──────────┴─────────────────────┘

Убедитесь также, что через JDBC Bridge можно записывать данные из ADQM во внешнюю базу данных. Для этого добавьте новую запись в таблицу ADQM:

INSERT INTO jdbc_table VALUES (5, '2023-09-28 14:15:16');

Затем проверьте содержимое таблицы на сервере MariaDB:

SELECT * FROM mariadb_table;

+----+---------------------+
| id | date                |
+----+---------------------+
|  1 | 2023-09-25 11:12:13 |
|  2 | 2023-09-26 12:13:14 |
|  3 | 2023-09-27 13:14:15 |
|  5 | 2023-09-28 14:15:16 |
+----+---------------------+

Нашли ошибку? Выделите текст и нажмите Ctrl+Enter чтобы сообщить о ней