Работа с драйверами JDBC/ADBC¶

TCS поддерживает работу с общедоступными драйверами для интерфейсов JDBC и ADBC по SQL-протоколу Apache Arrow Flight.

Примечание

В текущей версии TCS аутентификация по протоколу Apache Arrow Flight осуществляется по фиксированным учетным данным:

логин tcs
пароль tcs

Установка драйверов¶

Скачайте установочный пакет нужного драйвера по ссылке:

Подключение драйверов¶

Примечание

Инструкции по подключению драйверов составлены для локально развернутого кластера TCS.

Подключение драйвера JDBC к редактору DBeaver¶

Примечание

Перед подключением драйвера убедитесь, что поддержка драйверов JDBC/ADBC включена в конфигурации TCS.

В DBeaver добавьте драйвер JDBC для Arrow Flight SQL в качестве нового драйвера:

a. В меню выберите пункт Database > Driver Manager.

b. В диалоговом окне Driver manager нажмите Create.

c. В разделе Settings выполните следующие действия:
- В поле Name укажите имя драйвера, например JDBC Driver for Arrow Flight SQL.
- В поле Driver Type убедитесь, что выбран тип драйвера Generic.
- В поле Class Name укажите org.apache.arrow.driver.jdbc.ArrowFlightJdbcDriver.
- В поле URL Template укажите jdbc:arrow-flight-sql://{host}:{port} (например, jdbc:arrow-flight-sql://localhost:50051).
- В поле Default Port укажите порт 50051.
d. В разделе Libraries нажмите Add File и выберите .jar-файл для драйвера JDBC для Arrow Flight SQL.

e. Нажмите OK.
Создайте подключение к DBeaver, использующее ваш драйвер:

a. Выберите Database > New Connection from JDBC URL.

b. В поле Create New Connection в диалоговом окне JDBC URL введите jdbc:arrow-flight-sql://{host}:{port}?useEncryption=0 (например, jdbc:arrow-flight-sql://localhost:50051?useEncryption=0).

Свойство useEncryption=0 (false) необходимо указывать явно, поскольку при работе с текущей версией TCS поддерживаются только незашифрованные JDBC-соединения. Значение по умолчанию для этого свойства равно 1 (true).

В результате DBeaver добавит ваш драйвер в список Drivers.

c. Выберите ваш драйвер в списке Drivers и нажмите Next.

d. В диалоговом окне Connect to a Database укажите свои учетные данные для аутентификации. При работе с текущей версией TCS поддерживаются только JDBC-соединения по имени полозователя и паролю.
- В поле Username укажите tcs.
- В поле Password укажите tcs.
e. (необязательно) Нажмите Test Connection. Если подключение работает, откроется диалоговое окно Connection Test, в котором указывается, что DBeaver может подключиться к TCS. После попытки подключения соединение закрывается. Нажмите OK.

f. Нажмите Finish.

Подключение драйвера ADBC к Apache Superset¶

Примечание

Перед подключением драйвера убедитесь, что поддержка драйверов JDBC/ADBC включена в конфигурации TCS.

Склонируйте локально репозиторий Apache Superset https://github.com/apache/superset.
В локальном репозитории Apache Superset создайте файл docker/requirements-local.txt и впишите в него пакеты с зависимостями:
```
pyarrow==15.0.0
flightsql-dbapi==0.2.2
adbc-driver-flightsql==1.4.0
psycopg2-binary==2.9.10
```
Соберите и запустите Docker-образ Apache Superset с помощью Docker Compose:
```
export TAG=4.1.1
docker compose -f docker-compose-image-tag.yml up
```
Подробнее см. https://superset.apache.org/docs/installation/docker-compose/.
Подключитесь к веб-интерфейсу Apache Superset по HTTP-адресу http:/localhost:8088.
Добавьте новое соединение datafusion+flightsql://tcs:tcs@{host}:{port}?insecure=True (например, datafusion+flightsql://tcs:tcs@host.docker.internal:50051?insecure=True).

Подробнее см. https://superset.apache.org/docs/configuration/databases#connecting-through-the-ui.

Параметры строки соединения¶

Параметры строки соединения для каждого драйвера описаны в документации Apache Arrow:

Передача параметров из TCS-заголовков¶

В запросах, отсылаемых через драйверы JDBC/ADBC, можно задавать все параметры, которые поддерживаются в заголовках TCS.

Создайте новый SQL-скрипт:
- В редакторе DBeaver: пункт меню SQL Editor > New SQL script.
- В редакторе Apache Superset: пункт меню SQL > SQL Lab.
В теле скрипта укажите SQL-запрос и задайте нужные параметры с помощью команды SET, например:
```
SET tcs.reverse_order=FALSE;
SELECT * FROM "employees"."public"."attributes"
```
Для передачи нескольких параметров в одном запросе можно использовать любой из следующих вариантов синтаксиса:
- с помощью нескольких инструкций с командой SET:
```
SET tcs.only_buffer=TRUE;
SET tcs.reverse_order=FALSE;
SELECT * FROM "employees"."public"."attributes"
```
- с помощью одной инструкции с командой SET, где все параметры перечислены через запятую:
```
SET tcs.only_buffer=TRUE, tcs.reverse_order=FALSE;
SELECT * FROM "employees"."public"."attributes"
```
Выполните SQL-скрипт:
- В редакторе DBeaver: кнопка Execute SQL Script на панели слева.
- В редакторе Apache Superset: кнопка RUN снизу.

Выполнение пакетов подготовленных расчётов в JDBC¶

JDBC поддерживает объединение и исполнение нескольких подготовленных расчётов типа INSERT INTO в одном пакете (batch), что позволяет значительно ускорять операции с данными и выполнять операции, получая данные из Apache Spark.

Пример:

package com.simple_example;

import java.io.IOException;
import java.sql.DriverManager;
import java.sql.SQLException;

public class Main {
    private static final String connString = "jdbc:arrow-flight-sql://tcs:tcs@localhost:50051?useEncryption=false&user=tcs&password=tcs";

    public static void main(String[] args) throws SQLException, IOException {
        // Вставка данных.
        optimizedBatchPrepared();

        preparedSelect();
        preparedWithParams();
    }

    // Работа с PreparedStatement.
    static void preparedSelect() throws SQLException {
        var query = """
        SELECT avg(column1) as column1_avg
        FROM attributes
        """;

        var conn = DriverManager.getConnection(connString);
        var ps = conn.prepareStatement(query);

        ps.execute();
        var rs = ps.getResultSet();
        rs.next();

        var column1Avg = rs.getInt(1);
        System.out.println(column1Avg);

        ps.close();
        conn.close();
    }

    // Работа с параметризированным PreparedStatement.
    static void preparedWithParams() throws SQLException {
        var query = """
        SELECT COUNT(column1) as column1_count
        FROM attributes
        WHERE column2 = ?
        """;

        var conn = DriverManager.getConnection(connString);
        var ps = conn.prepareStatement(query);

        ps.setString(1, "2_foo");
        ps.execute();
        var rs = ps.getResultSet();
        rs.next();

        var column1Count = rs.getInt(1);
        System.out.println(column1Count);

        ps.close();
        conn.close();
    }

    // Работа с оптимизированным пакетным PreparedStatement для INSERT INTO.
    static void optimizedBatchPrepared() throws SQLException {
        var query = """
        INSERT INTO attributes(column1, column2)
        VALUES (?, ?)
        """;

        var conn = DriverManager.getConnection(connString);
        var ps = conn.prepareStatement(query);

        // Вставляем 1 тысячу строк
        for (int i = 0; i < 1000; i++) {
            // Добавляем 100 строк для вставки за один вызов.
            for (int j = 0; j < 100; j++) {
                ps.setInt(1, j);
                ps.setString(2, j + "_bar");
                ps.addBatch();
            }
        }
        ps.executeBatch();

        ps.close();
        conn.close();
    }
}

Подробнее см. документацию Oracle по addBatch().

Важно

Метод executeBatch() в TCS поддерживает только запросы вида INSERT INTO ... VALUES.

Работа с нематериализованными SQL-представлениями¶

Создание SQL-представления: доступно только через HTTP-запрос.
Просмотр списка всех доступных SQL-представлений:
- В редакторе DBeaver: нажать кнопку Refresh, все доступные SQL-представления отобразятся в списке Views.
- В редакторе Superset: нажать кнопку Refresh, все доступные SQL-представления отобразятся в списке TABLE.
Просмотр текста SQL-представления: в любом редакторе выбрать SQL-представление в списке, рядом отобразится его текст.
Замещение SQL-представления: доступно только через HTTP-запрос.
Удаление SQL-представления: доступно только через HTTP-запрос.

Version:

Работа с драйверами JDBC/ADBC¶

Установка драйверов¶

Подключение драйверов¶

Подключение драйвера JDBC к редактору DBeaver¶

Подключение драйвера ADBC к Apache Superset¶

Параметры строки соединения¶

Передача параметров из TCS-заголовков¶

Выполнение пакетов подготовленных расчётов в JDBC¶

Работа с нематериализованными SQL-представлениями¶